Rework sphinx configuration for PDF

- Add extension `sphinx.ext.imgconverter` to allow using `svg` images in pdfs.
- Customize pdf generation:
  - `parsec.pdf`: Contains the full documentation.
  - `parsec-userguide.pdf`: Contains only the `userguide/` documentation.
  - `parsec-adminguide.pdf`: Contains only the `adminguide/` documentation.
- Include only the index note & `history` on html

  Those elements are only usefull on the website.

- Update readthedocs configuration

  - Add a dockerfile to try locally a configuration.
  - Update readthedocs with the required apt packages from the dockerfile.

Other Changes
-------------

- Remove unused `development/index.rst`

  We don't include the dev related doc in the documentation anymore.
  So the `index.rst` in `development` wasn't in use and sphinx generate warning for it.

- Rework `docs/Makefile`

  - Make `latexpdf` & `latexpdfja` depends on `latex`.
  - Add variable `LATEXMKOPTS` to provide the option `-interaction=nonstopmode` by default to `latexmk`.

Author: FirelightFlagboy

.cspell/custom-words.txt

@@ -26,6 +26,10 @@ browserslistrc
 Bsas
 bxsalsa
 cachekey
+latexmk
+librsvg
+luatex
+LATEXMKOPTS
 CAFILE
 camelcase
 capacitorjs
@@ -90,8 +94,10 @@ farn
 fetchrow
 fetchval
 fghij
+firacode
 flate
 Flaticon
+fncychap
 Folderish
 fqcn
 Freepik
@@ -201,6 +207,8 @@ localdb
 LowLevel
 lproj
 lsregister
+lstfiracode
+lualatex
 MACBYTES
 MACFUSE
 makensis

.readthedocs.yml

@@ -9,6 +9,17 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.9"
+  # Must be the same list as defined in `docs/Dockerfile`.
+  # (You can exclude `make`, `python3{,-pip}` & `latexmk` since they're already present)
+  apt_packages:
+    - fonts-roboto
+    - fonts-firacode
+    - imagemagick
+    - librsvg2-bin
+    - texlive-luatex
+    - texlive-latex-base
+    - texlive-latex-recommended
+    - texlive-latex-extra
 
 # Build our docs in additional formats such as PDF
 formats:

docs/Dockerfile

@@ -0,0 +1,28 @@
+FROM ubuntu:22.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+    make \
+    python3 \
+    python3-pip \
+    # Install additional fonts for latex
+    fonts-roboto \
+    fonts-firacode \
+    # Required by `sphinx.ext.imgconverter`.
+    imagemagick \
+    librsvg2-bin \
+    # We use lualatex as latex engine.
+    texlive-luatex \
+    # Install requirement for latex.
+    texlive-latex-base \
+    texlive-latex-recommended \
+    texlive-latex-extra \
+    # The pdf is build using latexmk
+    latexmk
+
+# Generate with `poetry export --format=requirements.txt --only docs --output=docs/requirements.txt`
+# Then you need to remove the `python_version` requirement in the
+COPY requirements.txt /requirements.txt
+
+RUN python3 -m pip install -r requirements.txt

docs/Makefile

@@ -16,6 +16,7 @@ endif
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+LATEXMKOPTS     = -interaction=nonstopmode
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -110,16 +111,14 @@ latex:
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 		"(use \`make latexpdf' here to do that automatically)."
 
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+latexpdf: latex
 	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	$(MAKE) -C $(BUILDDIR)/latex LATEXMKOPTS=$(LATEXMKOPTS) all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+latexpdfja: latex
 	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	$(MAKE) -C $(BUILDDIR)/latex LATEXMKOPTS=$(LATEXMKOPTS) all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 text:

docs/conf.py

@@ -35,7 +35,14 @@ def fetch_parsec_version():
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx_rtd_theme"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx_rtd_theme",
+    # Allow to use svg images in latex build.
+    # https://www.sphinx-doc.org/en/master/usage/extensions/imgconverter.html
+    "sphinx.ext.imgconverter",
+]
 
 # Sphinx-intl config
 locale_dirs = ["locale/"]
@@ -129,7 +136,7 @@ def fetch_parsec_version():
     # 'sticky_navigation': True  # Set to False to disable the sticky nav while scrolling.
     "logo_only": True,  # if we have a html_logo below, this shows /only/ the logo with no title text
     "collapse_navigation": False,  # Collapse navigation (False makes it tree-like)
-    # 'display_version': True,  # Display the docs version
+    "display_version": True,  # Display the docs version
     # 'navigation_depth': 4,  # Depth of the headers shown in the navigation bar
 }
 
@@ -216,39 +223,74 @@ def fetch_parsec_version():
 
 # -- Options for LaTeX output ------------------------------------------
 
+latex_engine = "lualatex"
+
 latex_elements = {
+    #  Additional stuff for the LaTeX preamble.
+    "preamble": "\n".join(
+        [
+            # Use firecode in codeblocks.
+            r"\usepackage{lstfiracode}",
+        ]
+    ),
+    # Customize used font in latex
+    "fontpkg": "\n".join(
+        [
+            r"\usepackage{fontspec}",
+            r"\setmainfont{roboto}",
+            r"\setsansfont{roboto}",
+            r"\setmonofont{firacode}",
+        ]
+    ),
     # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    "papersize": "a4paper",
     #  The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
-    #  Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    "pointsize": "12pt",
+    "printindex": r"\footnotesize\raggedright\printindex",
+    "fncychap": r"\usepackage[Sonny]{fncychap}",
+    "babel": r"\usepackage{babel}",
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
-latex_documents = [("index", "parsec.tex", "Parsec Documentation", "Emmanuel Leblond", "manual")]
+latex_documents = [
+    ("index", "parsec.tex", "Parsec Documentation", "[email protected]", "howto"),
+    (
+        "userguide/index",
+        "parsec-userguide.tex",
+        "Parsec User Guide",
+        "[email protected]",
+        "howto",
+    ),
+    (
+        "adminguide/index",
+        "parsec-adminguide.tex",
+        "Parsec Admin Guide",
+        "[email protected]",
+        "howto",
+    ),
+]
 
 # The name of an image file (relative to this directory) to place at
 # the top of the title page.
-# latex_logo = None
+latex_logo = "parsec.png"
 
 # For "manual" documents, if this is true, then toplevel headings
 # are parts, not chapters.
-# latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
-# latex_show_pagerefs = False
+latex_show_pagerefs = False
 
 # If true, show URL addresses after external links.
-# latex_show_urls = False
+latex_show_urls = "no"
 
 # Documents to append as an appendix to all manuals.
 # latex_appendices = []
 
 # If false, no module index is generated.
-# latex_domain_indices = True
+latex_domain_indices = True
 
 
 # -- Options for manual page output ------------------------------------

docs/development/index.rst

@@ -1,8 +1,10 @@
 .. Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 (eventually AGPL-3.0) 2016-present Scille SAS
 
-.. note::
-    Parsec's documentation is available in several languages and versions.
-    Expand the "Read the Docs" panel at the bottom of the sidebar to see the list.
+.. only:: html
+
+   .. note::
+       Parsec's documentation is available in several languages and versions.
+       Expand the "Read the Docs" panel at the bottom of the sidebar to see the list.
 
 
 ===========
@@ -42,13 +44,14 @@ The main documentation for the site is organized into the following sections:
     roles
     cryptography
 
+.. only:: html
 
-.. toctree::
-    :maxdepth: 1
-    :caption: Development
-    :name: sec-devel
+   .. toctree::
+       :maxdepth: 1
+       :caption: Development
+       :name: sec-devel
 
-    history
+       history
 
 .. Indices and tables
 .. ------------------