From 6768f3ee19d4dab5519447898588a6be684d7c10 Mon Sep 17 00:00:00 2001
From: Graeme Watt <Graeme.Watt@durham.ac.uk>
Date: Fri, 3 Nov 2023 12:08:35 +0000
Subject: [PATCH] docs: fix epub and explain how to build local docs

* Add "html_title" to avoid warning when building epub format:
  WARNING: conf value "epub_title" (or "html_title") should not be
  empty for EPUB3
* Explain how to build docs locally using Sphinx in installation.rst.
* Add "SPHINXOPTS = -W --keep-going" to Makefile for Sphinx builds.
*
---
 docs/Makefile         |  2 +-
 docs/conf.py          |  4 ++--
 docs/installation.rst | 12 ++++++++++++
 3 files changed, 15 insertions(+), 3 deletions(-)

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
 # "<project> v<release> 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
 ------