From 6b142d9b0f67f2cca6856b722b96114ef7a2ca7b Mon Sep 17 00:00:00 2001 From: Brian Gunnarson <49216024+bgunnar5@users.noreply.github.com> Date: Wed, 28 Jun 2023 07:56:45 -0700 Subject: [PATCH] feature/pdf-docs (#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 | 2 ++ CHANGELOG.md | 3 +++ docs/source/conf.py | 13 ++++++++----- docs/source/faq.rst | 2 +- docs/source/merlin_developer.rst | 3 +-- docs/source/merlin_variables.rst | 2 +- docs/source/modules/installation/installation.rst | 2 +- 7 files changed, 17 insertions(+), 10 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index c1c252e30..ee62bcb5e 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,3 +11,5 @@ sphinx: python: install: - requirements: docs/requirements.txt + +formats: [pdf] \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 603086aaa..25ee73963 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 315978a6a..b578e8672 100644 --- a/docs/source/conf.py +++ b/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]). diff --git a/docs/source/faq.rst b/docs/source/faq.rst index d0ef8e109..3632aab6c 100644 --- a/docs/source/faq.rst +++ b/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`_ +`_ . This functionality is only available to launch a flux scheduler. diff --git a/docs/source/merlin_developer.rst b/docs/source/merlin_developer.rst index 08947ca89..e88352f3e 100644 --- a/docs/source/merlin_developer.rst +++ b/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 -`_. +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: diff --git a/docs/source/merlin_variables.rst b/docs/source/merlin_variables.rst index 7f545a4d2..d67e06412 100644 --- a/docs/source/merlin_variables.rst +++ b/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`, diff --git a/docs/source/modules/installation/installation.rst b/docs/source/modules/installation/installation.rst index d18261af5..96195ff3d 100644 --- a/docs/source/modules/installation/installation.rst +++ b/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 +++++++++++++++