Skip to content

[MRG+1] DOC: small reorganization of contributing.rst documentation section. #10685

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 25, 2018
Merged

[MRG+1] DOC: small reorganization of contributing.rst documentation section. #10685

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 38 additions & 29 deletions doc/developers/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.::

Expand All @@ -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 <https://github.com/search?utf8=%E2%9C%93&q=sphinx+repo%3Ascikit-learn%2Fscikit-learn+extension%3Ash+path%3Abuild_tools%2Fcircle&type=Code>`_
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
Expand All @@ -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
<viewing_rendered_html_documentation>` very handy.

Finally, follow the formatting rules below to make it consistently good:

* Add "See also" in docstrings for related classes/functions.
Expand All @@ -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 <https://github.com/search?utf8=%E2%9C%93&q=sphinx+repo%3Ascikit-learn%2Fscikit-learn+extension%3Ash+path%3Abuild_tools%2Fcircle&type=Code>`_
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
<viewing_rendered_html_documentation>` very handy.

.. _testing_coverage:

Expand Down