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

[Lukas Bulwahn <lukas.bulwahn@xxxxxxxxx>]

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@xxxxxxxxx>
> Signed-off-by: John Mathew <john.mathew@xxxxxxxxxx>
> ---
>  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
> 
>