Reorganize the documentation table of content

[Pierre-Sassoulas]

Type of Changes

	Type
✓	📜 Docs

Description

Create a user guide part and a developper guide part to distinguish the two. First step for #5728. If we want to do that properly (old links working) we need to do quite a lot of redirection.

Link that need to still works after this:
https://pylint--6589.org.readthedocs.build/en/6589/user_guide/index.html
https://pylint--6589.org.readthedocs.build/en/6589/development_guide/index.html
https://pylint--6589.org.readthedocs.build/en/6589/development_guide/contribute.html
https://pylint--6589.org.readthedocs.build/en/6589/how_tos/custom_checkers.html
https://pylint--6589.org.readthedocs.build/en/6589/how_tos/index.html
https://pylint--6589.org.readthedocs.build/en/6589/how_tos/plugins.html
https://pylint--6589.org.readthedocs.build/en/6589/how_tos/transform_plugins.html
https://pylint--6589.org.readthedocs.build/en/6589/technical_reference/checkers.html
https://pylint--6589.org.readthedocs.build/en/6589/technical_reference/index.html
https://pylint--6589.org.readthedocs.build/en/6589/technical_reference/startup.html
https://pylint--6589.org.readthedocs.build/en/6589/technical_reference/features.html
https://pylint--6589.org.readthedocs.build/en/6589/user_guide/options.html
https://pylint--6589.org.readthedocs.build/en/6589/user_guide/ide_integration/ide-integration.html
https://pylint--6589.org.readthedocs.build/en/6589/development_guide/tests/index.html
https://pylint--6589.org.readthedocs.build/en/6589/development_guide/tests/install.html
https://pylint--6589.org.readthedocs.build/en/6589/development_guide/tests/launching_test.html
https://pylint--6589.org.readthedocs.build/en/6589/development_guide/tests/writting_test.html
https://pylint--6589.org.readthedocs.build/en/6589/development_guide/contributor_guide.html
https://pylint--6589.org.readthedocs.build/en/6589/user_guide/ide_integration/flymake-emacs.html
https://pylint--6589.org.readthedocs.build/en/6589/user_guide/ide_integration/textmate.html
https://pylint--6589.org.readthedocs.build/en/6589/user_guide/pre-commit-integration.html
https://pylint--6589.org.readthedocs.build/en/6589/user_guide/options.html
https://pylint--6589.org.readthedocs.build/en/6589/user_guide/output.html
https://pylint--6589.org.readthedocs.build/en/6589/user_guide/run.html

[coveralls]

Pull Request Test Coverage Report for Build 2373165816

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 237 unchanged lines in 22 files lost coverage.
• Overall coverage remained the same at 95.414%

---

Files with Coverage Reduction	New Missed Lines	%
pylint/extensions/private_import.py	1	99.15%
pylint/lint/parallel.py	1	95.59%
pylint/checkers/init.py	2	94.12%
pylint/checkers/format.py	4	96.21%
pylint/checkers/refactoring/refactoring_checker.py	4	98.37%
pylint/reporters/text.py	5	85.61%
pylint/utils/file_state.py	5	95.24%
pylint/epylint.py	6	86.67%
pylint/utils/linterstats.py	6	95.83%
pylint/checkers/refactoring/recommendation_checker.py	7	96.26%

Totals
Change from base Build 2370722387:	0.0%
Covered Lines:	16230
Relevant Lines:	17010

---

💛 - Coveralls

[DanielNoord]

I haven't looked at anything yet, but saw some of the renames. Just my two cents:
I don't think we should move the changelog under User guide or Developer guide. For me they are not really what I would expect to be part of a "guide" and also it is probably one of the most visited pages, so it makes sense to have it in the index bar immediately.

I do like how we're restructuring the documentation, but I would suggest something like:

Tutorial
User guide/Using pylint
Development
Additional commands
Changelogs
Contact

I think those headers clearly separate the different functions the documentation serves and points users to their desired place quickly and efficiently.

[Pierre-Sassoulas]

All options and features are really close in content, should we only keep features and rename it pylint's options ?

[DanielNoord]

Is there anything in features that isn't covered by messages and all-options?

[Pierre-Sassoulas]

Ha I suppose features is the one we should suppress, but I liked its appearance better than all-options.

[DanielNoord]

I haven't looked at the actual code just want to finalise the structure first. Some comments:

1. Shall we move pylint features and optional pylint checkers from configuration to either the top-level or a new checkers sub-category? They don't really fit in configuration, especially after we remove the stuff about options.
2. Let's also expand the developer guide like you did with the user guide. Contributing can be a top-level link for example.
3. Let's move around Support and Changelog. The changelog is probably something people want to look at more often than our contact page.

This is starting to look really good 😄

[Pierre-Sassoulas]

Just did 2) 3).

I think as we did 2) we need to regroup some subsection so the table of content do not take too much space vertically.

Shall we move pylint features and optional pylint checkers from configuration to either the top-level or a new checkers sub-category? They don't really fit in configuration, especially after we remove the stuff about options.

I don't know if pylint_features can be moved to somewhere it makes more sense because there is too much in it with too little sections and it's hard to make sense of it without reading everything.

In general option/configuration doc is a mess. I think we need to add more link and explanation in the generated documentation and rely on it more, or entirely. For example we could add links to option affecting a messages in the messages documentation and link to messages being affected by an option in the option documentation. Or we could be moving the RST documentation to the code so the generated doc integrate the old rst doc automatically. Then we can remove the old manually typed rst and focus on making the generated doc better. I think this is something that can wait for 2.15 though.

There's some thing I'm thinking about doing before 2.15:

4. Merging how toes and technical references (without yet trying to make them coherent together)
5. finding a way to make "running pylint" and "pylint output" be part of an option or configuration section ?

[DanielNoord]

Okay, just a proposal based on the current subsections:

**User guide**
Installation
- Command line
- Editor and IDE integration
- Pre-commit integration
- Show your usage
Usage and output
- Running pylint
- Pylint output
Messages
- Messages overview
- Messages control
Configuration
- All pylint options
- Naming styles
Checkers
- Pylint features
- Optional pylint checkers

Same number of subsections as now, but with a better separation of messages, configuration and checkers.

**Developer guide**
API
- Pylint
- epylint
Guides and technical reference
- Guides for writing plugins
-- How to write a checker
-- How to write a Pylint plugin
-- Transform plugins
- Technical reference
-- Startup and the Linter Class
-- Checkers
Contributing to pylint
- Contributing
- Testing
- Profiling and performance analysis
- Releasing a pylint version

Two sections removed compared to current version with more sub-levels. I think we should set max-level to 3 here so that they can be seen when you expand them.

The rest stays the same.

[Pierre-Sassoulas]

Applied the new toc with the exceptions of the Guides and technical reference level, I kept the two sub levels because I think we're likely to merge or refactor those so may as well keep them close to what they are. I need to check the redirect again before this is mergeable. Removing the "All pylint options" makes the TOC a lot better imo and it's now the only header in the configuration section so it make sense.

[DanielNoord]

@Pierre-Sassoulas One more question before I (finally) review this. Have you considered keeping the files in their current place but only changing the toctrees? That would make the old links work while we can still show the structure we want on the site itself.

[Pierre-Sassoulas]

We could have done that but that would make future maintenance harder (toctree un clear) in order to not have to do redirection now and I just (laboriousely 😄) did the redirections so I think there's no benefits anymore

[DanielNoord]

One final move I would make.

As for content, some of the new index.rst files are a little empty. But I think that's fine for now. Let's worry about the structure first!

[jacobtylerwalls]

While here, may as well fix some language!