diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst index 036f020115d4f..7117d9ade4348 100644 --- a/doc/developers/contributing.rst +++ b/doc/developers/contributing.rst @@ -422,13 +422,18 @@ documents live in the source code repository under the ``doc/`` directory. You can edit the documentation using any text editor, and then generate the HTML output by building the documentation website. -**Building the documentation** +Building the documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^ Building the documentation requires the ``sphinx``, ``sphinx-gallery``, ``numpydoc``, ``matplotlib``, and ``Pillow`` packages:: pip install sphinx sphinx-gallery numpydoc matplotlib Pillow +To build the documentation, you need to be in the ``doc`` folder:: + + cd doc + It also requires having the version of scikit-learn installed that corresponds to the documentation, e.g.:: @@ -452,9 +457,20 @@ To build the PDF manual, run:: make latexpdf -**When you are writing documentation**, it is important to keep a good -compromise between mathematical and algorithmic details, and give -intuition to the reader on what the algorithm does. +.. warning:: **Sphinx version** + + While we do our best to have the documentation build under as many + versions of Sphinx as possible, the different versions tend to + behave slightly differently. To get the best results, you should + use the same version as the one we used on CircleCI. Look at this + `github search `_ + to know the exact version. + +Guidelines for writing documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is important to keep a good compromise between mathematical and algorithmic +details, and give intuition to the reader on what the algorithm does. Basically, to elaborate on the above, it is best to always start with a small paragraph with a hand-waving explanation of what the @@ -479,24 +495,6 @@ documentation with the maths makes it more friendly towards users that are just interested in what the feature will do, as opposed to how it works "under the hood". -When you change the documentation in a pull request, CircleCI automatically -builds it. To view the documentation generated by CircleCI: - -* navigate to the bottom of your pull request page to see the CI - statuses. You may need to click on "Show all checks" to see all the CI - statuses. -* click on the CircleCI status with "python3" in the title. -* add ``#artifacts`` at the end of the URL. Note: you need to wait for the - CircleCI build to finish before being able to look at the artifacts. -* once the artifacts are visible, navigate to ``doc/_changed.html`` to see a - list of documentation pages that are likely to be affected by your pull - request. Navigate to ``doc/index.html`` to see the full generated html - documentation. - -If you often need to look at the documentation generated by CircleCI, e.g. when -reviewing pull requests, you may find :ref:`this tip -` very handy. - Finally, follow the formatting rules below to make it consistently good: * Add "See also" in docstrings for related classes/functions. @@ -514,15 +512,26 @@ Finally, follow the formatting rules below to make it consistently good: * For "References" in docstrings, see the Silhouette Coefficient (:func:`sklearn.metrics.silhouette_score`). -.. warning:: **Sphinx version** +Generated documentation on CircleCI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - While we do our best to have the documentation build under as many - versions of Sphinx as possible, the different versions tend to - behave slightly differently. To get the best results, you should - use the same version as the one we used on CircleCI. Look at this - `github search `_ - to know the exact version. +When you change the documentation in a pull request, CircleCI automatically +builds it. To view the documentation generated by CircleCI: + +* navigate to the bottom of your pull request page to see the CI + statuses. You may need to click on "Show all checks" to see all the CI + statuses. +* click on the CircleCI status with "python3" in the title. +* add ``#artifacts`` at the end of the URL. Note: you need to wait for the + CircleCI build to finish before being able to look at the artifacts. +* once the artifacts are visible, navigate to ``doc/_changed.html`` to see a + list of documentation pages that are likely to be affected by your pull + request. Navigate to ``doc/index.html`` to see the full generated html + documentation. +If you often need to look at the documentation generated by CircleCI, e.g. when +reviewing pull requests, you may find :ref:`this tip +` very handy. .. _testing_coverage: