feature/pdf-docs (LLNL#427)

* first attempt at adding pdf

* fixing build error

* modify changelog to show docs changes

* fix errors Luc found in the build logs

* trying out removal of latex

* reverting latex changes back

* uncommenting the latex_elements settings

* adding epub to see if latex will build

* adding a latex engine variable to conf

* fix naming error with latex_engine

* attempting to add a logo to the pdf build

* testing an override to the searchtools file

* revert back to not using searchtools override

* update changelog

.readthedocs.yaml

@@ -11,3 +11,5 @@ sphinx:
 python:
   install:
     - requirements: docs/requirements.txt
+
+formats: [pdf]

CHANGELOG.md

@@ -7,13 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [unreleased]
 ### Fixed
 - A bug where the .orig, .partial, and .expanded file names were using the study name rather than the original file name
+- Some build warnings in the docs (unknown targets, duplicate targets, title underlines too short, etc.)
 
 ### Added
 - Tests for ensuring `$(MERLIN_SPEC_ORIGINAL_TEMPLATE)`, `$(MERLIN_SPEC_ARCHIVED_COPY)`, and `$(MERLIN_SPEC_EXECUTED_RUN)` are stored correctly
+- A pdf download format for the docs
 
 ### Changed
 - The ProvenanceYAMLFileHasRegex condition for integration tests now saves the study name and spec file name as attributes instead of just the study name
   - This lead to minor changes in 3 tests ("local override feature demo", "local pgen feature demo", and "remote feature demo") with what we pass to this specific condition
+- Uncommented Latex support in the docs configuration to get pdf builds working
 
 ## [1.10.1]
 ### Fixed

docs/source/conf.py

@@ -66,7 +66,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -122,21 +122,24 @@
 
 # -- Options for LaTeX output ------------------------------------------------
 
+latex_engine = "pdflatex"
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
-    # 'papersize': 'letterpaper',
+    'papersize': 'letterpaper',
     # The font size ('10pt', '11pt' or '12pt').
     #
-    # 'pointsize': '10pt',
+    'pointsize': '10pt',
     # Additional stuff for the LaTeX preamble.
     #
-    # 'preamble': '',
+    'preamble': '',
     # Latex figure (float) alignment
     #
-    # 'figure_align': 'htbp',
+    'figure_align': 'htbp',
 }
 
+latex_logo = "../images/merlin.png"
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).

docs/source/faq.rst

@@ -383,7 +383,7 @@ in the ``launch_args`` variable in the batch section.
 What is PBS?
 ~~~~~~~~~~~~
 Another job scheduler. See `Portable Batch System
-https://en.wikipedia.org/wiki/Portable_Batch_System`_
+<https://en.wikipedia.org/wiki/Portable_Batch_System>`_
 .
 This functionality is only available to launch a flux scheduler.
 

docs/source/merlin_developer.rst

@@ -164,8 +164,7 @@ properties labeled ``name`` and ``population`` that are both required, it would
     }
 
 Here, ``name`` can only be a string but ``population`` can be both a string and an integer. 
-For help with json schema formatting, check out the `step-by-step getting started guide 
-<https://json-schema.org/learn/getting-started/step-by-step.html>`_.
+For help with json schema formatting, check out the `step-by-step getting started guide`_.
 
 The next step is to enable this block in the schema validation process. To do this we need to:
 

docs/source/merlin_variables.rst

@@ -161,7 +161,7 @@ Reserved variables
             $(MERLIN_INFO)/*.expanded.yaml
 
 The ``LAUNCHER`` Variable
-+++++++++++++++++++++
++++++++++++++++++++++++++
 
 ``$(LAUNCHER)`` is a special case of a reserved variable since it's value *can* be changed.
 It serves as an abstraction to launch a job with parallel schedulers like :ref:`slurm<slurm>`,

docs/source/modules/installation/installation.rst

@@ -229,7 +229,7 @@ If everything is set up correctly, you should see:
 
 
 (OPTIONAL) Docker Advanced Installation
-----------------------------
+---------------------------------------
 
 RabbitMQ Server
 +++++++++++++++