diff --git a/docs/Makefile b/docs/Makefile index d5a220e..4c33eee 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -W --keep-going SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build diff --git a/docs/conf.py b/docs/conf.py index f1960ca..e60c9c0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -74,7 +74,7 @@ def __getattr__(cls, name): master_doc = 'index' # General information about the project. -project = u'' +project = u'HEPData Converter' copyright = u'2016, CERN' author = u'CERN' @@ -167,7 +167,7 @@ def __getattr__(cls, name): # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +html_title = f"{project} v{version} documentation" # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None diff --git a/docs/installation.rst b/docs/installation.rst index 7d7abdb..e3812be 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -65,6 +65,18 @@ Developers can then run the tests with the following command: python -m unittest discover hepdata_converter/testsuite 'test_*' +The documentation can be built locally in the virtual environment using Sphinx: + +.. code:: console + + (venv)$ pip install -e '.[docs]' + (venv)$ cd docs + (venv)$ make html + +Then view the output by opening a web browser at ``_build/html/index.html``. +Developers should also check that they can successfully build other formats using ``make latexpdf`` and ``make epub``. +All three formats will be built by *Read the Docs* for the ``main`` branch on GitHub. + Docker ------