Skip to content

Commit

Permalink
Add note to Sphinx from requirements.txt in editing_these_docs.rst
Browse files Browse the repository at this point in the history
Installing from the requirements.txt file will make sure that the
the version number constraints will be applied during installation
of Sphinx anbd its dependencies.

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>
  • Loading branch information
yantosca committed May 20, 2022
1 parent 37d1048 commit 571a5b7
Showing 1 changed file with 21 additions and 18 deletions.
39 changes: 21 additions & 18 deletions docs/source/reference/editing_these_docs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
Editing this User Guide
#######################

This user guide is generated with `Sphinx <https://www.sphinx-doc.org/>`_.
Sphinx is an open-source Python project designed to make writing software documentation easier.
This user guide is generated with `Sphinx <https://www.sphinx-doc.org/>`_.
Sphinx is an open-source Python project designed to make writing software documentation easier.
The documentation is written in a reStructuredText (it's similar to markdown), which Sphinx extends for software documentation.
The source for the documentation is the :file:`docs/source` directory in top-level of the source code.

Expand All @@ -15,14 +15,17 @@ Quick start
===========

To build this user guide on your local machine, you need to install Sphinx. Sphinx is a Python 3 package and
it is available via :program:`pip`. This user guide uses the Read The Docs theme, so you will also need to
it is available via :program:`pip`. This user guide uses the Read The Docs theme, so you will also need to
install :literal:`sphinx-rtd-theme`. It also uses the `sphinxcontrib-bibtex <https://pypi.org/project/sphinxcontrib-bibtex/>`_
and `recommonmark <https://recommonmark.readthedocs.io/>`_ extensions, which you'll need to install.

.. code-block:: console
$ pip install sphinx sphinx-rtd-theme sphinxcontrib-bibtex recommonmark
$ cd $KPP_HOME/docs
$ pip install -r requirements.txt
Installing with :file:`requirements.txt` will make sure that the
proper versions of Sphinx and its dependencies will be installed.

To build this user guide locally, navigate to the :file:`docs/` directory and make the :literal:`html` target.

Expand All @@ -34,7 +37,7 @@ To build this user guide locally, navigate to the :file:`docs/` directory and ma
This will build the user guide in :file:`docs/build/html`, and you can
open :file:`index.html` in your web-browser. The source files for the
user guide are found in :file:`docs/source`.
user guide are found in :file:`docs/source`.

.. note::

Expand All @@ -50,27 +53,27 @@ can be easily miswritten. Two important things you should know right away are:
* Indents are 3-spaces
* "Things" are separated by 1 blank line. For example, a list or
code-block following a paragraph should be separated from the
paragraph by 1 blank line.
paragraph by 1 blank line.

You should keep these in mind when you're first getting
started. Dedicating an hour to learning reST will save you time in the
long-run. Below are some good resources for learning reST.

* `reStructuredText primer
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_:
(single best resource; however, it's better read than skimmed)
(single best resource; however, it's better read than skimmed)
* Official `reStructuredText reference
<https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_
(there is *a lot* of information here)
(there is *a lot* of information here)
* `Presentation by Eric Holscher
<https://www.youtube.com/watch?v=eWNiwMwMcr4>`_ (co-founder of Read
The Docs) at DjangoCon US 2015 (the entire presentation is good, but
reST is described from 9:03 to 21:04)
reST is described from 9:03 to 21:04)
* `YouTube tutorial by Audrey Tavares's
<https://www.youtube.com/watch?v=DSIuLnoKLd8>`_
<https://www.youtube.com/watch?v=DSIuLnoKLd8>`_

A good starting point would be Eric Holscher's presentations followed
by the reStructuredText primer.
by the reStructuredText primer.

================
Style guidelines
Expand All @@ -96,19 +99,19 @@ For **titles and headers**:
the :literal:`:file:` role.

**Program names** (e.g. :program:`cmake`) occuring in the text should
use the :literal:`:program:` role.
use the :literal:`:program:` role.

**OS-level commands** (e.g. :command:`rm`) occuring in the text should
use the :literal:`:command:` role.
use the :literal:`:command:` role.

**Environment variables** occuring in the text should use the
:literal:`:envvar:` role.
:literal:`:envvar:` role.

**Inline code** or code variables occuring in the text should use the
:literal:`:code:` role.
:literal:`:code:` role.

**Code snippets** should use :literal:`.. code-block:: <language>`
directive like so
directive like so

.. code-block:: none
Expand All @@ -117,7 +120,7 @@ directive like so
import gcpy
print("hello world")
The language can be "none" to omit syntax highlighting.
The language can be "none" to omit syntax highlighting.

For command line instructions, the "console" language should be
used. The :literal:`$` should be used to denote the console's
Expand All @@ -126,4 +129,4 @@ instructions, a prompt like :literal:`gcuser:~/path1/path2$` should be
used.

**Inline literals** (e.g. the :literal:`$` above) should use the
:literal:`:literal:` role.
:literal:`:literal:` role.

0 comments on commit 571a5b7

Please sign in to comment.