Docs: final changes before merging the revamp

* Update autogenerated `verdi` docs. * Fix `docs_path` in `docs/source/conf.py`. * Enable `warnings turn into errors` for docs-build. * Remove obsolete page `configuration`. * Move some unresolved references into todo-items. Sections `how-to:codes:transport` and `how-to:codes:scheduler` are not yet written. * Replace `sphinx.ext.imgmath` with `sphinx.ext.mathjax`. This way, latex is no longer required for documentation builds. * Add temporary fix for `pydata-sphinx-theme` issue #193. * Add AiiDA team twitter account to docs conf `html_theme_options` Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
aiidateam · Jun 2, 2020 · 8e69062 · 8e69062
1 parent 8c25cfe
commit 8e69062
Show file tree

Hide file tree

Showing 12 changed files with 36 additions and 69 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -28,7 +28,7 @@ jobs:
           # nit-picky mode, turn warnings into errors,
           # but do not stop the build on errors (so we can still inspect the doc artifacts)
           command: |
-            sphinx-build -b html -n --keep-going -d docs/_build/doctrees docs/source docs/_build/html
+            sphinx-build -b html -n -W --keep-going -d docs/_build/doctrees docs/source docs/_build/html
       - store_artifacts:
           path: docs/_build/html/
           destination: html

diff --git a/docs/source/_static/aiida-custom.css b/docs/source/_static/aiida-custom.css
@@ -4,7 +4,11 @@ a.nav-link.nav-external i {
     font-size: inherit !important;
     vertical-align: inherit !important;
 }
-
+/* Current fix for /~https://github.com/pandas-dev/pydata-sphinx-theme/issues/193 */
+dl.field-list {
+    display: grid;
+    grid-template-columns: fit-content(30%) minmax(0, 1fr);
+}
 /* For icon unicodes see https://fontawesome.com/v4.7.0/icons/  */
 .title-icon-rocket .admonition-title:before {
     margin-right:.5rem;

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -45,7 +45,7 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.intersphinx', 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.viewcode', 'sphinx.ext.coverage',
-    'sphinx.ext.imgmath', 'sphinx.ext.ifconfig', 'sphinx.ext.todo', 'IPython.sphinxext.ipython_console_highlighting',
+    'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.todo', 'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive', 'aiida.sphinxext', 'sphinx_panels', 'sphinx_copybutton'
 ]
 ipython_mplbackend = ''
@@ -183,13 +183,14 @@
         {'url': 'http://www.aiida.net/', 'name': 'AiiDA Home'}
     ],
     'github_url': '/~https://github.com/aiidateam/aiida-core',
+    'twitter_url': 'https://twitter.com/aiidateam',
     'use_edit_page_button': True,
 }
 html_context = {
     'github_user': 'aiidateam',
     'github_repo': 'aiida-core',
     'github_version': 'master',
-    'doc_path': 'docs',
+    'doc_path': 'docs/source',
 }
 panels_add_boostrap_css = False  # pydata-sphinx-theme already loads this
 html_logo = 'images/AiiDA_transparent_logo.png'

diff --git a/docs/source/howto/codes.rst b/docs/source/howto/codes.rst
@@ -11,7 +11,11 @@ This plugin must contain the instructions necessary for the engine to be able to
 2. Run the code with the correct set of command line parameters
 
 The following subsections will not only take you through the process of :ref:`creating the calculation plugin<how-to:codes:interfacing>` and then using these to actually :ref:`run the code<how-to:codes:run>`.
-It will also show examples on how to implement tools that are commonly coupled with the running of a calculation, such as :ref:`the parsing of outputs<how-to:codes:parsing>`, :ref:`the communication with external machines<how-to:codes:transport>` and the interaction with its :ref:`scheduling software<how-to:codes:scheduler>`.
+It will also show examples on how to implement tools that are commonly coupled with the running of a calculation, such as :ref:`the parsing of outputs<how-to:codes:parsing>`.
+
+.. todo::
+
+    Add to preceding sentence: :ref:`the communication with external machines<how-to:codes:transport>` and the interaction with its :ref:`scheduling software<how-to:codes:scheduler>`.
 
 Some general guidelines to keep in mind are:
 

diff --git a/docs/source/howto/plugins.rst b/docs/source/howto/plugins.rst
@@ -5,7 +5,11 @@ How to package plugins
 **********************
 
 This section focuses on how to *package* AiiDA extensions (plugins) so that they can be tested, published and eventually reused by others.
-For guides on writing specific extensions, see :ref:`how-to:codes:interfacing`, :ref:`how-to:codes:scheduler`, :ref:`how-to:codes:transport` or :ref:`how-to:data:plugin`.
+For guides on writing specific extensions, see :ref:`how-to:codes:interfacing` and :ref:`how-to:data:plugin`.
+
+.. todo::
+
+    For guides on writing specific extensions, see :ref:`how-to:codes:interfacing`, -ref-'how-to:codes:scheduler', -ref-'how-to:codes:transport' or :ref:`how-to:data:plugin`.
 
 
 .. _how-to:plugins:bundle:

diff --git a/docs/source/install/configuration.rst b/docs/source/install/configuration.rst
diff --git a/docs/source/intro/tutorial.rst b/docs/source/intro/tutorial.rst
@@ -680,7 +680,7 @@ We have also compiled useful how-to guides that are especially relevant for the
 
         Connecting to supercomputers
             To setup up a computer which can communicate with a HPC over SSH, see the :ref:`running on supercomputers how-to <how-to:installation:running-on-supercomputers>`, or add a :ref:`custom transport <how-to:codes:transport>`.
-            AiiDA has pre-written scheduler plugins to work with LSF, PBSPro, SGE, Slurm and Torque, or you can add a :ref:`custom scheduler <how-to:codes:scheduler>`.
+            AiiDA has pre-written scheduler plugins to work with LSF, PBSPro, SGE, Slurm and Torque.
 
         Working with external codes
             Existing calculation plugins, for interfacing with external codes, are available on the `aiida plugin registry <https://aiidateam.github.io/aiida-registry/>`_.
@@ -696,3 +696,7 @@ We have also compiled useful how-to guides that are especially relevant for the
             Once you have a working plugin, you may also wish to :ref:`package it into a python module <how-to:plugins>` for others to use.
 
 .. You can do more with AiiDA than basic arithmetic! Check out some cool real-world examples of AiiDA in action on the `demo page <LINK HERE>
+
+.. todo::
+
+    Add to "Connecting to supercomputers": , or you can add a :ref:`custom scheduler <how-to:codes:scheduler>`.
diff --git a/docs/source/reference/command_line.rst b/docs/source/reference/command_line.rst
@@ -546,7 +546,6 @@ Below is a list with all available subcommands.
       -H, --hostname HOSTNAME  Hostname.
       -P, --port INTEGER       Port number.
       -c, --config-dir PATH    Path to the configuration directory
-      --debug                  Enable debugging
       --wsgi-profile           Whether to enable WSGI profiler middleware for
                                finding bottlenecks
 

diff --git a/requirements/requirements-py-3.5.txt b/requirements/requirements-py-3.5.txt
@@ -88,6 +88,7 @@ py==1.8.1
 pyblake2==1.1.2
 PyCifRW==4.4.1
 pycparser==2.20
+pydata-sphinx-theme==0.3.0
 PyDispatcher==2.0.5
 Pygments==2.6.1
 pymatgen==2019.7.2
@@ -121,8 +122,8 @@ six==1.14.0
 snowballstemmer==2.0.0
 spglib==1.14.1.post0
 Sphinx==2.4.4
-sphinx-rtd-theme==0.4.3
-sphinx-panels==0.1.0
+sphinx-copybutton==0.2.11
+sphinx-panels==0.4.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-contentui==0.2.4
 sphinxcontrib-details-directive==0.1.0

diff --git a/requirements/requirements-py-3.6.txt b/requirements/requirements-py-3.6.txt
@@ -87,6 +87,7 @@ ptyprocess==0.6.0
 py==1.8.1
 PyCifRW==4.4.1
 pycparser==2.20
+pydata-sphinx-theme==0.3.0
 PyDispatcher==2.0.5
 Pygments==2.6.1
 pymatgen==2020.3.2
@@ -120,8 +121,8 @@ six==1.14.0
 snowballstemmer==2.0.0
 spglib==1.14.1.post0
 Sphinx==2.4.4
-sphinx-rtd-theme==0.4.3
-sphinx-panels==0.1.0
+sphinx-copybutton==0.2.11
+sphinx-panels==0.4.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-contentui==0.2.4
 sphinxcontrib-details-directive==0.1.0

diff --git a/requirements/requirements-py-3.7.txt b/requirements/requirements-py-3.7.txt
@@ -86,6 +86,7 @@ ptyprocess==0.6.0
 py==1.8.1
 PyCifRW==4.4.1
 pycparser==2.20
+pydata-sphinx-theme==0.3.0
 PyDispatcher==2.0.5
 Pygments==2.6.1
 pymatgen==2020.3.2
@@ -119,8 +120,8 @@ six==1.14.0
 snowballstemmer==2.0.0
 spglib==1.14.1.post0
 Sphinx==2.4.4
-sphinx-rtd-theme==0.4.3
-sphinx-panels==0.1.0
+sphinx-copybutton==0.2.11
+sphinx-panels==0.4.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-contentui==0.2.4
 sphinxcontrib-details-directive==0.1.0

diff --git a/requirements/requirements-py-3.8.txt b/requirements/requirements-py-3.8.txt
@@ -85,6 +85,7 @@ ptyprocess==0.6.0
 py==1.8.1
 PyCifRW==4.4.1
 pycparser==2.20
+pydata-sphinx-theme==0.3.0
 PyDispatcher==2.0.5
 Pygments==2.6.1
 pymatgen==2020.3.2
@@ -118,8 +119,8 @@ six==1.14.0
 snowballstemmer==2.0.0
 spglib==1.14.1.post0
 Sphinx==2.4.4
-sphinx-rtd-theme==0.4.3
-sphinx-panels==0.1.0
+sphinx-copybutton==0.2.11
+sphinx-panels==0.4.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-contentui==0.2.4
 sphinxcontrib-details-directive==0.1.0