Skip to content

Commit

Permalink
rework text
Browse files Browse the repository at this point in the history
  • Loading branch information
@jessica-mitchell
jessica-mitchell committed Aug 30, 2023
1 parent 10bc68f commit c001496
Showing 1 changed file with 98 additions and 88 deletions.
186 changes: 98 additions & 88 deletions ...eveloper_space/workflows/documentation_workflow/user_documentation_workflow.rst
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
.. _userdoc_workflow:

User-level documentation workflow
#################################
=================================

What you need to know
+++++++++++++++++++++
Overview of workflow
--------------------

We use `Sphinx <https://www.sphinx-doc.org/en/master/>`_ to generate
documentation and `Read the Docs <https://readthedocs.org/>`_ to
publish it. Sphinx uses reStructuredText as the base format for the
documentation. To learn more about the syntax, check out this `quick
reference
<https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_.
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.

The NEST Simulator documentation lives alongside its code. It is
contained in the ``doc/htmldoc`` directory within the `NEST source
Expand All @@ -21,8 +21,6 @@ We work with `GitHub <https://www.github.com>`_ as a web-based hosting
service for Git. Git allows us to keep our versions under control,
with each release of NEST having its own documentation.

This workflow aims for the concept of **user-correctable documentation**.

.. mermaid::
:zoom:
:caption: Overview of documentation build. Drag and zoom to explore.
Expand All @@ -31,7 +29,7 @@ This workflow aims for the concept of **user-correctable documentation**.

sphinx:::TextPosition

classDef TextPosition padding-right:20em, padding-top:10em;
classDef TextPosition padding-right:25em;
classDef orangeFill color:#fff, stroke:#f63, stroke-width:2px, fill:#f63;
classDef blueFill color:#fff, stroke:#072f42, stroke-width:2px, fill:#072f42;
classDef brownFill color:#fff, stroke:#652200, stroke-width:2px, fill:#652200;
Expand All @@ -46,42 +44,44 @@ This workflow aims for the concept of **user-correctable documentation**.
Parse_rst-->build
build(Build output formats):::blueFill
end
subgraph SOURCE FILES
source(repo: nest/nest-simulator):::orangeFill-->read
subgraph EDIT SOURCE FILES
source(repo: nest/nest-simulator):::orangeFill-- sphinx-build-->read
end

subgraph OUTPUT["OUTPUT"]
subgraph OUTPUT["REVIEW OUTPUT"]
direction TB
build--local-->local(_build directory):::brownFill
build-->rtd(Read the Docs):::brownFill
build--local filesystem-->local(_build directory):::brownFill
build--hosting platform-->rtd(Read the Docs):::brownFill
local-->HTML(HTML):::brownFill
rtd-->HTML
end


.. note::
This workflow shows you how to create **user-level documentation**
for NEST. For the **developer documentation**, please refer to our
:ref:`Developer documentation workflow
<devdoc_workflow>`.
Contribute to the documentation
-------------------------------

Changing the documentation
++++++++++++++++++++++++++

If you notice any errors or weaknesses in the documentation, please
submit an `Issue <https://github.com/nest/nest-simulator/issues>`_ in
our GitHub repository.

You can also make changes directly to your forked copy of the `NEST source
You can make changes directly to your forked copy of the `NEST source
code repository <https://github.com/nest/nest-simulator>`_ and create a `pull
request <https://github.com/nest/nest-simulator/pulls>`_. Just follow the
workflow below!

Setting up your environment
+++++++++++++++++++++++++++
If you have not done so alrealdy first

#. Fork the nest-simulator repository (see :ref:`here <fork>` for details on first time setup)

We recommend that you set up a full NEST developer environment using
Conda (for details on Conda, see :ref:`conda_tips`):
#. Clone the nest-simulator:

.. code-block:: bash
git clone git@github.com:<my-username>/nest-simulator
Set up your environment
~~~~~~~~~~~~~~~~~~~~~~~

Using the Conda package (includes everything to build NEST, including documentation)
````````````````````````````````````````````````````````````````````````````````````

For details on Conda, see :ref:`conda_tips`

.. code-block:: bash
Expand All @@ -96,6 +96,9 @@ If you later on want to deactivate or delete the build environment:
conda deactivate
rm -rf conda/
Using pip (includes packages for documentation only)
````````````````````````````````````````````````````

If you want to install only a minimal set of packages for building the
documentation and avoid using Conda, you can use pip:

Expand All @@ -110,41 +113,68 @@ If you use pip, install ``pandoc`` from your platform's package manager (e.g. ap
sudo apt-get install pandoc
Generating documentation with Sphinx
++++++++++++++++++++++++++++++++++++
Edit and create pages
~~~~~~~~~~~~~~~~~~~~~~

Now that you activated your environment, you can generate HTML files using
Sphinx.
You can now edit or add new files with your editor of choice. Most documentation files are
written in reStructuredText and are found in the ``doc/htmldoc`` directory. There are some exceptions, detailed below.
If you're unfamiliar with reStructuredText, you can find some
`helpful hints here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.

Rendering HTML
~~~~~~~~~~~~~~
Please see our :ref:`documentation style guide <doc_styleguide>` for information on how to write good documentation in NEST.

You can build and preview the documentation locally by running the following
commands.

1. Clone the NEST repository:
Where to find documentation in the repository
`````````````````````````````````````````````

.. code-block:: bash
Most documentation is located in ``doc/htmldoc`` with some exceptions.

If you want to edit Model docs, PyNEST API files, or PyNEST examples, you will need to edit the source files:

.. list-table::
:header-rows: 1

git clone git@github.com:nest/nest-simulator
* - Type of documentation
- Source location
* - Model docs
- ``nest-simulator/models/*.h`` in the section `BeginUserDocs`
* - PyNEST API
- ``nest-simulator/pynest/nest/**/*.py``
* - PyNEST examples
- ``nest-simulator/pynest/examples/**/*.py``

2. Navigate to the ``doc/htmldoc`` folder:

.. note::


Also consider that any new pages you create need to be referenced in the relevant
table of contents.



Review changes you made
~~~~~~~~~~~~~~~~~~~~~~~

To check that the changes you made are correct in the HTML output,
you will need to build the documentation locally with Sphinx.

#. Navigate to the ``doc/htmldoc`` folder:

.. code-block:: bash
cd nest-simulator/doc/htmldoc
3. Build the docs:
#. Build the docs:

.. code-block:: bash
sphinx-build . ../_build/html -b html
4. Preview files. They are located in ``doc/_build/html``
#. Preview files. They are located in ``doc/_build/html``

.. code-block:: bash
browser ../_build/html/index.html
<browser> ../_build/html/index.html
.. tip::

Expand All @@ -155,61 +185,41 @@ commands.
cmake -Dwith-userdoc=ON </path/to/NEST/src>
make docs
Editing and creating pages
~~~~~~~~~~~~~~~~~~~~~~~~~~

To edit existing `reStructuredText <https://thomas-cokelaer.info/tutorials/
sphinx/rest_syntax.html>`_ files or to create new ones, follow the steps below:

1. You can edit and/or add ``.rst`` files in the ``doc/htmldoc`` directory using your
editor of choice.

2. If you create a new page, open ``index.rst`` in the ``doc/htmldoc`` directory
and add the file name under ``.. toctree::``. This will ensure it appears on
the NEST Simulator documentation's table of contents.
3. If you rename or move a file, please make sure you update all the
corresponding cross-references.
4. Save your changes.
Create a pull request
~~~~~~~~~~~~~~~~~~~~~

5. Re-render documentation as described above.
Once you're happy with the changes, you can submit a pull request on Github from your fork.
Github has a nice help page that outlines the process for
`submitting pull requests <https://help.github.com/articles/using-pull-requests/#initiating-the-pull-request>`_.

.. note::

Please see our :ref:`documentation style guide <doc_styleguide>` for information on how to write good documentation in the NEST style.

Proceed as follows to preview your version of the documentation on Read the
Docs.
Reviewers will be assigned and go through your changes.

1. Check that unwanted directories are listed in ``.gitignore``:

.. code-block:: bash
If you are a first time contributor, we ask that you fill out the
:download:`NEST Contributor Agreement <https://nest-simulator.readthedocs.io/en/latest/_downloads/9b65adbdacba6bfed66e68c62af4e308/NEST_Contributor_Agreement.pdf>`
form to transfer your copyright to the NEST initiative and send it to *info [at] nest-initiative.org*.

_build
_static
_templates
.. tip::

2. Add, commit and push your changes to GitHub.
If you notice any errors or weaknesses in the documentation, you can
also submit an `Issue <https://github.com/nest/nest-simulator/issues>`_ on
GitHub.

3. Go to `Read the Docs <https://readthedocs.org/>`_. Sign up for an account
if you don't have one.

4. `Import <https://readthedocs.org/dashboard/import/>`_ the project.
.. seealso::

5. Enter the details of your project in the ``repo`` field and hit ``Create``.
This workflow shows you how to create **user-level documentation**
for NEST. For the **developer documentation**, please refer to our
:ref:`Developer documentation workflow
<devdoc_workflow>`.

6. `Build <https://docs.readthedocs.io/en/stable/intro/
import-guide.html#building-your-documentation>`_ your documentation.

This allows you to preview your work on your Read the Docs account. In order
to see the changes on the official NEST Simulator documentation, please submit
a pull request.
Read the Docs
``````````````

Creating pull request
+++++++++++++++++++++
NEST documentation is hosted on Read the Docs. If you would like to view the documentation
on Read the Docs, you can set up your own account and link it with your Github account.

Once your documentation work is finished, you can create a
:ref:`pull request <git_workflow>` to the ``master``
branch of the NEST Source Code Repository. Your pull request will be reviewed
by the NEST Documentation Team!
See `this guide <https://docs.readthedocs.io/en/stable/intro/import-guide.htmli>`_
for more information.

0 comments on commit c001496

Please sign in to comment.