From 0b2fec2344e8cd019d26716460e52f81b1d38640 Mon Sep 17 00:00:00 2001 From: Tim Jenness Date: Mon, 8 Apr 2024 14:28:39 -0700 Subject: [PATCH 1/8] Switch to documenteer guide doc build --- docs/conf.py | 74 +------------------------------------------ docs/documenteer.toml | 10 ++++++ docs/requirements.txt | 3 +- 3 files changed, 12 insertions(+), 75 deletions(-) create mode 100644 docs/documenteer.toml diff --git a/docs/conf.py b/docs/conf.py index d5949e59..8a3e8c83 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,76 +3,4 @@ # Sphinx configuration file # see metadata.yaml in this repo for to update document-specific metadata -import os - -import sphinx_rtd_theme -from documenteer.sphinxconfig.utils import form_ltd_edition_name - - -extensions = [ - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.mathjax', - 'sphinx.ext.ifconfig', - 'sphinx-prompt', - 'sphinxcontrib.bibtex', - 'documenteer.sphinxext', - 'documenteer.sphinxext.bibtex', -] - -html_theme = 'sphinx_rtd_theme' -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -version = form_ltd_edition_name( - git_ref_name=os.getenv('TRAVIS_BRANCH', default='main')) -# The full version, including alpha/beta/rc tags. -release = version - -project = 'lsst-texmf: The LSST LaTeX Classes' -html_title = project -html_short_title = 'lsst-texmf' - -author = 'LSST Data Management' - -copyright = '2017-2021 Association of Universities for Research in Astronomy (AURA), Inc.' - -master_doc = 'index' - -html_context = { - # Enable "Edit in GitHub" link - 'display_github': True, - 'github_user': 'lsst', - 'github_repo': 'lsst-texmf', - # TRAVIS_BRANCH is available in CI, but main is a safe default - 'github_version': os.getenv('TRAVIS_BRANCH', default='main') + '/docs/' -} - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = '_static/lsst-logo-dark.svg' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -templates_path = ['_templates'] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['README.rst', '_build'] - -source_encoding = 'utf-8' - -# BibTeX configuration -bibtex_bibfiles = [ - '../texmf/bibtex/bib/lsst.bib', - '../texmf/bibtex/bib/books.bib', - '../texmf/bibtex/bib/lsst-dm.bib', - '../texmf/bibtex/bib/refs.bib', - '../texmf/bibtex/bib/refs_ads.bib', -] - -# Intersphinx configuration. -# http://www.sphinx-doc.org/en/stable/ext/intersphinx.html -intersphinx_mapping = {} +from documenteer.conf.guide import * # noqa diff --git a/docs/documenteer.toml b/docs/documenteer.toml new file mode 100644 index 00000000..69ee05b6 --- /dev/null +++ b/docs/documenteer.toml @@ -0,0 +1,10 @@ +[project] +title = "lsst-texmf: The LSST LaTeX Classes" +copyright = "2016-2024 Association of Universities for Research in Astronomy, Inc. (AURA)" +base_url = "https://lsst-texmf.lsst.io" +github_url = "https://github.com/lsst/lsst-texmf" + +extensions = [ + "sphinxcontrib.bibtex", + "documenteer.ext.bibtex", +] diff --git a/docs/requirements.txt b/docs/requirements.txt index e6379b37..3e4c95a2 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,3 @@ -documenteer>=0.6,<1.0 +documenteer[guide] sphinx-rtd-theme==0.2.4 sphinx-prompt -sphinx <7 From 549c51da3673ff8ee24de402bd5162582780a8bc Mon Sep 17 00:00:00 2001 From: Tim Jenness Date: Mon, 8 Apr 2024 15:28:16 -0700 Subject: [PATCH 2/8] Enable bibtex in guide Co-authored-by: Jonathan Sick --- docs/conf.py | 14 ++++++++++++++ docs/documenteer.toml | 1 + 2 files changed, 15 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 8a3e8c83..923b141e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,3 +4,17 @@ # see metadata.yaml in this repo for to update document-specific metadata from documenteer.conf.guide import * # noqa + + +# BibTeX configuration +bibtex_bibfiles = [ + '../texmf/bibtex/bib/lsst.bib', + '../texmf/bibtex/bib/books.bib', + '../texmf/bibtex/bib/lsst-dm.bib', + '../texmf/bibtex/bib/refs.bib', + '../texmf/bibtex/bib/refs_ads.bib', +] + +# Feel free to experiment with other options +bibtex_default_style = "lsst_aa" +bibtex_reference_style = "author_year" diff --git a/docs/documenteer.toml b/docs/documenteer.toml index 69ee05b6..52180278 100644 --- a/docs/documenteer.toml +++ b/docs/documenteer.toml @@ -4,6 +4,7 @@ copyright = "2016-2024 Association of Universities for Research in Astronomy, In base_url = "https://lsst-texmf.lsst.io" github_url = "https://github.com/lsst/lsst-texmf" +[sphinx] extensions = [ "sphinxcontrib.bibtex", "documenteer.ext.bibtex", From f48d6d7a4a0ea2ef80f821bde3ebdbbe062da9c9 Mon Sep 17 00:00:00 2001 From: Tim Jenness Date: Mon, 8 Apr 2024 15:31:12 -0700 Subject: [PATCH 3/8] Fix label in example memo --- docs/examples/MEMO-nnn.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/MEMO-nnn.rst b/docs/examples/MEMO-nnn.rst index c2ff9326..0fdeea5b 100644 --- a/docs/examples/MEMO-nnn.rst +++ b/docs/examples/MEMO-nnn.rst @@ -1,4 +1,4 @@ -.. _DMTN-nnn: +.. _MEMO-nnn: ################################ Memo example - use any series From 87be160db2abb274768023f8ce0c0365bfcdec71 Mon Sep 17 00:00:00 2001 From: Tim Jenness Date: Mon, 8 Apr 2024 15:44:11 -0700 Subject: [PATCH 4/8] Mask readme from sphinx build --- docs/documenteer.toml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/documenteer.toml b/docs/documenteer.toml index 52180278..850a5a87 100644 --- a/docs/documenteer.toml +++ b/docs/documenteer.toml @@ -9,3 +9,6 @@ extensions = [ "sphinxcontrib.bibtex", "documenteer.ext.bibtex", ] +exclude = [ + "_templates/README.md" # This markdown file is not part of the documentation +] From f28da7b614d93ade1eab7c09c8c8f4a4f01abc00 Mon Sep 17 00:00:00 2001 From: Tim Jenness Date: Mon, 8 Apr 2024 15:44:29 -0700 Subject: [PATCH 5/8] Remove trailing whitespace --- texmf/tex/latex/lsst/lsstdoc.cls | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/texmf/tex/latex/lsst/lsstdoc.cls b/texmf/tex/latex/lsst/lsstdoc.cls index a3f7ed03..9a702d08 100644 --- a/texmf/tex/latex/lsst/lsstdoc.cls +++ b/texmf/tex/latex/lsst/lsstdoc.cls @@ -403,7 +403,7 @@ \newcommand{\mkmemotitle}{ \thispagestyle{empty} - \newgeometry{top= 1cm,left=2cm,bottom=1cm, right=2cm} + \newgeometry{top= 1cm,left=2cm,bottom=1cm, right=2cm} \vspace*{-30pt} \includegraphics[width=4cm]{rubin_logo} @@ -411,14 +411,14 @@ \begin{minipage}{0.3\textwidth} \begin{flushright} \vspace*{-50pt} - \large + \large 950 North Cherry Avenue, Tucson, AZ, 85719. \vspace{3mm} - \textbf{\docDate} + \textbf{\docDate} \end{flushright} \end{minipage} - + \vspace{10pt} \textbf {To: \memoto}\\ \textbf {From: \@author}\\ @@ -1109,8 +1109,8 @@ No actions have been identified.} % ----------------------------------------------------------------------------- % Useful definition % ----------------------------------------------------------------------------- -\def\VRO{Vera C. Rubin Observatory~} -\def\RO{Rubin Observatory~} +\def\VRO{Vera C. Rubin Observatory~} +\def\RO{Rubin Observatory~} \def\aaps{A\&AS} % Astronomy and Astrophysics Suplement \def\aap{A\&A} % Astronomy and Astrophysics \def\ssr{Space~Sci.~Rev.} % Space Science Reviews From 0aeea5fee18680b64378d03ed49fb0c85102f67a Mon Sep 17 00:00:00 2001 From: Tim Jenness Date: Mon, 8 Apr 2024 15:44:55 -0700 Subject: [PATCH 6/8] Fix Jira ticket URL --- texmf/tex/latex/lsst/lsstdoc.cls | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/texmf/tex/latex/lsst/lsstdoc.cls b/texmf/tex/latex/lsst/lsstdoc.cls index 9a702d08..1fb767d7 100644 --- a/texmf/tex/latex/lsst/lsstdoc.cls +++ b/texmf/tex/latex/lsst/lsstdoc.cls @@ -1392,7 +1392,7 @@ No actions have been identified.} \newcommand{\reqparam}[1]{\margin@req{#1}} % Reference a JIRA ticket -\newcommand{\jira}[1]{\href{https://jira.lsstcorp.org/browse/#1}{#1}} +\newcommand{\jira}[1]{\href{https://rubinobs.atlassian.net/browse/#1}{#1}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% From 5aae5be56e692740f0e8819d75c4d6cdb6111781 Mon Sep 17 00:00:00 2001 From: Tim Jenness Date: Mon, 8 Apr 2024 15:46:04 -0700 Subject: [PATCH 7/8] Fix black formatting --- docs/conf.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 923b141e..07d26628 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -5,14 +5,13 @@ from documenteer.conf.guide import * # noqa - # BibTeX configuration bibtex_bibfiles = [ - '../texmf/bibtex/bib/lsst.bib', - '../texmf/bibtex/bib/books.bib', - '../texmf/bibtex/bib/lsst-dm.bib', - '../texmf/bibtex/bib/refs.bib', - '../texmf/bibtex/bib/refs_ads.bib', + "../texmf/bibtex/bib/lsst.bib", + "../texmf/bibtex/bib/books.bib", + "../texmf/bibtex/bib/lsst-dm.bib", + "../texmf/bibtex/bib/refs.bib", + "../texmf/bibtex/bib/refs_ads.bib", ] # Feel free to experiment with other options From 93b379a897c31a03de1931f7a166f29e16078a32 Mon Sep 17 00:00:00 2001 From: Tim Jenness Date: Mon, 8 Apr 2024 15:47:33 -0700 Subject: [PATCH 8/8] Remove some trailing whitespace --- texmf/bibtex/bib/books.bib | 12 ++++++------ texmf/bibtex/bib/refs.bib | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/texmf/bibtex/bib/books.bib b/texmf/bibtex/bib/books.bib index 2e683148..a333825e 100644 --- a/texmf/bibtex/bib/books.bib +++ b/texmf/bibtex/bib/books.bib @@ -360,12 +360,12 @@ @Book{1982mmme.book.....B } -@BOOK{NAP26141, - author = "National Academies of Sciences, Engineering and Medicine", - title = "Pathways to Discovery in Astronomy and Astrophysics for the 2020s", - isbn = "978-0-309-46734-6", - doi = "10.17226/26141", - abstract ="We live in a time of extraordinary discovery and progress in astronomy and astrophysics. The next decade will transform our understanding of the universe and humanity's place in it. Every decade the U.S. agencies that provide primary federal funding for astronomy and astrophysics request a survey to assess the status of, and opportunities for the Nation's efforts to forward our understanding of the cosmos. Pathways to Discovery in Astronomy and Astrophysics for the 2020s identifies the most compelling science goals and presents an ambitious program of ground- and space-based activities for future investment in the next decade and beyond. The decadal survey identifies three important science themes for the next decade aimed at investigating Earth-like extrasolar planets, the most energetic processes in the universe, and the evolution of galaxies. The Astro2020 report also recommends critical near-term actions to support the foundations of the profession as well as the technologies and tools needed to carry out the science.", +@BOOK{NAP26141, + author = "National Academies of Sciences, Engineering and Medicine", + title = "Pathways to Discovery in Astronomy and Astrophysics for the 2020s", + isbn = "978-0-309-46734-6", + doi = "10.17226/26141", + abstract ="We live in a time of extraordinary discovery and progress in astronomy and astrophysics. The next decade will transform our understanding of the universe and humanity's place in it. Every decade the U.S. agencies that provide primary federal funding for astronomy and astrophysics request a survey to assess the status of, and opportunities for the Nation's efforts to forward our understanding of the cosmos. Pathways to Discovery in Astronomy and Astrophysics for the 2020s identifies the most compelling science goals and presents an ambitious program of ground- and space-based activities for future investment in the next decade and beyond. The decadal survey identifies three important science themes for the next decade aimed at investigating Earth-like extrasolar planets, the most energetic processes in the universe, and the evolution of galaxies. The Astro2020 report also recommends critical near-term actions to support the foundations of the profession as well as the technologies and tools needed to carry out the science.", url = "https://nap.nationalacademies.org/catalog/26141/pathways-to-discovery-in-astronomy-and-astrophysics-for-the-2020s", year =2021, publisher = "The National Academies Press", diff --git a/texmf/bibtex/bib/refs.bib b/texmf/bibtex/bib/refs.bib index 9cf828e7..9eee0f59 100644 --- a/texmf/bibtex/bib/refs.bib +++ b/texmf/bibtex/bib/refs.bib @@ -2311,7 +2311,7 @@ @MISC{FIPS200 @MISC{TCISSG, publisher = {The NSF Cybersecurity Center of Excellence}, -author = {Andrew Adams and Kay Avila and Elisa Heymann and Mark Krenz and Jason R. Lee and +author = {Andrew Adams and Kay Avila and Elisa Heymann and Mark Krenz and Jason R. Lee and Barton P. Miller and Sean Peisert }, title = {Guide to Securing Scientific Software },