Re: [RFC PATCH v8 1/3] docs: scheduler: Restructure scheduler documentation.

Lukas Bulwahn
2020-09-09T10:32:14Z

On Wed, 2 Sep 2020, John Mathew wrote:

> Add new sections to enable addition of new documentation on
> the scheduler. Existing documentation is moved under the related
> new sections. The sections are
> - overview
> - sched-features
> - arch-specific.rst
> - sched-debugging.rst
>
> Suggested-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
> Signed-off-by: John Mathew <john.mathew@unikie.com>
> ---
> Documentation/scheduler/arch-specific.rst | 12 +++++++++
> Documentation/scheduler/index.rst | 30 +++++++++++----------
> Documentation/scheduler/overview.rst | 5 ++++
> Documentation/scheduler/sched-debugging.rst | 14 ++++++++++
> Documentation/scheduler/sched-features.rst | 25 +++++++++++++++++
> 5 files changed, 72 insertions(+), 14 deletions(-)
> create mode 100644 Documentation/scheduler/arch-specific.rst
> create mode 100644 Documentation/scheduler/overview.rst
> create mode 100644 Documentation/scheduler/sched-debugging.rst
> create mode 100644 Documentation/scheduler/sched-features.rst
>
> diff --git a/Documentation/scheduler/arch-specific.rst b/Documentation/scheduler/arch-specific.rst
> new file mode 100644
> index 000000000000..3e5af3a0695e
> --- /dev/null
> +++ b/Documentation/scheduler/arch-specific.rst
> @@ -0,0 +1,12 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Architecture Specific Scheduler Implementation Differences
> +==========================================================

That is a terribly long title, how about Architecture Specifics?

I am wondering if this should be on the toplevel documentation structure
directly under Linux Scheduler.

I think the x86 and MIPS context switch documentation could be placed
under Process context switching in a section Architecture Specifics.

> +
> +.. class:: toc-title
> +
> + Table of contents
> +
> +.. toctree::
> + :maxdepth: 2
> +
> diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
> index 88900aabdbf7..6e88a070c503 100644
> --- a/Documentation/scheduler/index.rst
> +++ b/Documentation/scheduler/index.rst
> @@ -1,24 +1,26 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> ===============
> Linux Scheduler
> ===============
>
> -.. toctree::
> - :maxdepth: 1
> +This documentation outlines the Linux kernel scheduler with its concepts,
> +details about the scheduler design and its data structures and architecture
> +specific implementation differences.
> +
>
> +.. class:: toc-title
> +
> + Table of contents
> +
> +.. toctree::
> + :maxdepth: 2
>
> - completion
> - sched-arch
> - sched-bwc
> - sched-deadline
> + overview
> sched-design-CFS
> - sched-domains
> - sched-capacity
> - sched-energy
> - sched-nice-design
> - sched-rt-group
> - sched-stats
> -
> - text_files
> + sched-features
> + arch-specific
> + sched-debugging
>
> .. only:: subproject and html
>
> diff --git a/Documentation/scheduler/overview.rst b/Documentation/scheduler/overview.rst
> new file mode 100644
> index 000000000000..a1d2d26629eb
> --- /dev/null
> +++ b/Documentation/scheduler/overview.rst
> @@ -0,0 +1,5 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +====================
> +Scheduler overview

s/Scheduler overview/Scheduler Overview/

for some more consistent capitalisation.

> +====================
> \ No newline at end of file

That could be the cause for the git am errors.

> diff --git a/Documentation/scheduler/sched-debugging.rst b/Documentation/scheduler/sched-debugging.rst
> new file mode 100644
> index 000000000000..e332069f99d6
> --- /dev/null
> +++ b/Documentation/scheduler/sched-debugging.rst
> @@ -0,0 +1,14 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Scheduler Debugging Interface
> +==============================
> +
> +.. class:: toc-title
> +
> + Table of contents
> +
> +.. toctree::
> + :maxdepth: 2
> +
> + sched-stats
> + text_files
> diff --git a/Documentation/scheduler/sched-features.rst b/Documentation/scheduler/sched-features.rst
> new file mode 100644
> index 000000000000..8eb90e86e489
> --- /dev/null
> +++ b/Documentation/scheduler/sched-features.rst
> @@ -0,0 +1,25 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Scheduler Features
> +===================
> +
> +.. class:: toc-title
> +
> + Table of contents
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + completion
> + sched-arch
> + sched-bwc
> + sched-deadline
> + sched-domains
> + sched-capacity
> + sched-energy
> + sched-nice-design
> + sched-rt-group
> + sched-stats
> +
> + text_files

I guess it is fine to place everything here for now, but more clean-up
would probably move those to the appropriate documentation structure,
right?

> +
> --
> 2.17.1
>
>