diff --git a/docs/contributing/docs.rst b/docs/contributing/docs.rst new file mode 100644 index 0000000..9b12301 --- /dev/null +++ b/docs/contributing/docs.rst @@ -0,0 +1,231 @@ +===================== +Writing documentation +===================== + +.. note:: + + Heavily inspired by the + `django project's guidelines `_ + +We place a high importance on consistency, readability and completeness of documentation. +If a feature is not documented, it does not exist. If a behavior is not documented, +it is a bug! We try to treat our +documentation like we treat our code: we aim to improve it as often as +possible. + +Documentation changes generally come in two forms: + +* General improvements: typo corrections, error fixes and better + explanations through clearer writing and more examples. + +* New features: documentation of features that have been added to the + framework since the last release. + +This section explains how writers can craft their documentation changes +in the most useful and least error-prone ways. + +Getting the raw documentation +============================= + +Though TLJH's documentation is intended to be read as HTML at +https://the-littlest-jupyterhub.readthedocs.io/, we edit it as a collection of text files for +maximum flexibility. These files live in the top-level ``docs/`` directory of +TLJH's repository. + +If you'd like to start contributing to our docs, get the development version of +TLJH from the source code repository. The development version has the +latest-and-greatest documentation, just as it has latest-and-greatest code. + +Getting started with Sphinx +=========================== + +TLJH's documentation uses the Sphinx__ documentation system, which in turn +is based on docutils__. The basic idea is that lightly-formatted plain-text +documentation is transformed into HTML, PDF, and any other output format. + +__ http://sphinx-doc.org/ +__ http://docutils.sourceforge.net/ + +To build the documentation locally, install Sphinx: + +.. console:: + + $ pip install Sphinx + +Then from the ``docs`` directory, build the HTML: + +.. console:: + + $ make html + +To get started contributing, you'll want to read the :ref:`reStructuredText +reference `. + +Your locally-built documentation will be themed differently than the +documentation at `the-littlest-jupyterhub.readthedocs.io `_. +This is OK! If your changes look good on your local machine, they'll look good +on the website. + +How the documentation is organized +================================== + +The documentation is organized into several categories: + +* **Tutorials** take the reader by the hand through a series + of steps to create something. + + The important thing in a tutorial is to help the reader achieve something + useful, preferably as early as possible, in order to give them confidence. + + Explain the nature of the problem we're solving, so that the reader + understands what we're trying to achieve. Don't feel that you need to begin + with explanations of how things work - what matters is what the reader does, + not what you explain. It can be helpful to refer back to what you've done and + explain afterwards. + +* **Topic guides** aim to explain a concept or subject at a + fairly high level. + + Link to reference material rather than repeat it. Use examples and don't be + reluctant to explain things that seem very basic to you - it might be the + explanation someone else needs. + + Providing background context helps a newcomer connect the topic to things + that they already know. + +* **Reference guides** contain technical reference for APIs. + They describe the functioning of TLJH's internal machinery and instruct in + its use. + + Keep reference material tightly focused on the subject. Assume that the + reader already understands the basic concepts involved but needs to know or + be reminded of how TLJH does it. + + Reference guides aren't the place for general explanation. If you find + yourself explaining basic concepts, you may want to move that material to a + topic guide. + +* **How-to guides** are recipes that take the reader through + steps in key subjects. + + What matters most in a how-to guide is what a user wants to achieve. + A how-to should always be result-oriented rather than focused on internal + details of how TLJH implements whatever is being discussed. + + These guides are more advanced than tutorials and assume some knowledge about + how TLJH works. Assume that the reader has followed the tutorials and don't + hesitate to refer the reader back to the appropriate tutorial rather than + repeat the same material. + +* **Troubleshooting guides** help reader answer the question "Why is my JupyterHub + not working?". + + These guides help readers try find causes for their symptoms, and hopefully fix + the issues. Some of these need to be specific to cloud providers, and that is + acceptable. + +Writing style +============= + +When using pronouns in reference to a hypothetical person, such as "a user with +a running notebook", gender neutral pronouns (they/their/them) should be used. +Instead of: + +* he or she... use they. +* him or her... use them. +* his or her... use their. +* his or hers... use theirs. +* himself or herself... use themselves. + +Commonly used terms +=================== + +Here are some style guidelines on commonly used terms throughout the +documentation: + +* **TLJH** -- common abbreviation of The Littlest JupyterHub. Fully + capitalized except when used in code / the commandline. + +* **Python** -- when referring to the language, capitalize Python. + +* **Notebook Interface** -- generic term for referring to JupyterLab, + nteract, classic notebook & other user interfaces for accessing + + +Guidelines for reStructuredText files +===================================== + +These guidelines regulate the format of our reST (reStructuredText) +documentation: + +* In section titles, capitalize only initial words and proper nouns. + +* Wrap the documentation at 120 characters wide, unless a code example + is significantly less readable when split over two lines, or for another + good reason. + + +* Use these heading styles:: + + === + One + === + + Two + === + + Three + ----- + + Four + ~~~~ + + Five + ^^^^ + +Documenting new features +======================== + +Our policy for new features is: + + All new features must have appropriate documentation before they + can be merged. + +Minimizing images +================= + +Optimize image compression where possible. For PNG files, use OptiPNG and +AdvanceCOMP's ``advpng``: + +.. code-block:: console + + $ cd docs + $ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"` + $ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"` + +This is based on OptiPNG version 0.7.5. Older versions may complain about the +``--strip all`` option being lossy. + +Spelling check +============== + +Before you commit your docs, it's a good idea to run the spelling checker. +You'll need to install a couple packages first: + +* `pyenchant `_ (which requires + `enchant `_) + +* `sphinxcontrib-spelling + `_ + +Then from the ``docs`` directory, run ``make spelling``. Wrong words (if any) +along with the file and line number where they occur will be saved to +``_build/spelling/output.txt``. + +If you encounter false-positives (error output that actually is correct), do +one of the following: + +* Surround inline code or brand/technology names with grave accents (`). +* Find synonyms that the spell checker recognizes. +* If, and only if, you are sure the word you are using is correct - add it + to ``docs/spelling_wordlist`` (please keep the list in alphabetical order). diff --git a/docs/index.rst b/docs/index.rst index 1e5219c..ca494d9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -52,4 +52,5 @@ to people contributing in various ways. .. toctree:: :titlesonly: + contributing/docs contributing/dev-setup