dmaluenda / scipiondocs Goto Github PK

You can find the last built docs on https://scipion-em.github.io/docs/

Scipion's documentation is built using Sphinx and hosted on GitHub pages. Sphinx uses certain files like *.rst files and Sphinx's config conf.py to build the docs on HTML, which we can later copy to some server. In our case, we the different versions of our docs on the docs GitHub repository . At the time of this writing we have only one version, the branch release-3.0.0, but we'll have more versions in the future. The branch gh-pages contains the built documentation for all versions (i.e. HTML files). When new commits are pushed to this branch,

will update and reflect them automatically.

On a high level, the docs have two main parts:

• The API docs, which are automatically generated from the code's docstrings using sphinx-apidoc. To build these, we need a working :doc:`installation of Scipion </docs/scipion-modes/install-from-sources>` in our machine.
• The general docs, which are manually generated content (e.g. guides, tutorials, etc).

From the root folder of this repo type

scipion3 run pip install -r requirements.txt
scipion3 run sphinx-multiversion . build

Documentation is generated by branch, currently we are dealing just with release-3.0.0 so you'll find it here:

build/release-3.0.0/index.html

Alternative you could locally run to verify build is ok:

scipion3 run sphinx-build . build/<your-branch>

The api docs are contained in the folder api of the scipion docs repository. To update them, we need to run sphinx-apidoc. Please note that this step is not necessary if you're just adding your own written .rst file.

We can set this up as a run configuration in PyCharm (Recommended):

Or alternatively, run this in the command line inside scipion-docs repo dir:

(sphinx-env) $ sphinx-apidoc -f -e -o api/ ~/git/scipion/pyworkflow ~/git/scipion/pyworkflow/tests/*

• -f forces to overwrite existing files
• -e generates one rst file per module
• api/ put output files here
• ~/git/scipion/pyworkflow is the source python code we want to generate docs for
• ~/git/scipion/pyworkflow/tests/* avoid generating docs for files matching this pattern.

1. You can reference python objects!! E.g. :class:`The plugin class<pyworkflow.plugin.Plugin>`. For more info check the sphinx guide on how to reference python objects
2. You can install and use `pandoc<https://pandoc.org/>`_ to convert from Markdown (.md) to .rst
3. The custom css is at _static/custom.css. To connect the css to a build documentation do:

rm build/release-3.0.0/_static/custom.css
ln -s _static/custom.css build/release-3.0.0/_static/

4. Finding targets:

scipion3 run python -m sphinx.ext.intersphinx build/release-3.0.0/objects.inv

5.- Linking to other sections in other pages, use ref tag:

:ref:`project.newProtocol() <pyworkflow.project.project.Project.newProtocol>`

6.- Linking to pages: Although the rst link will work for the final build, they will not work for a local build

` link text <page_identifier>`_

It is better to use:

:doc:`link text <page_identifier>`

7.- Linking contained PDFs.

PDFs are not built and has to be treated separately. First, place the PDF at _static/pdfs/my-new.pdf Then, link it relative to your page, e.g.:

`my-new.pdf <../../_static/pdfs/my-new.pdf>`__

8.- Process a single file

scipion3 run sphinx-build .  build docs/developer/symmetries.rst

will only update the "symmetry" page