From a86a8abd72dfdec2a9b7d7b8f814ee7fc327db68 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 20 Oct 2022 14:01:28 -0400 Subject: [PATCH 1/6] Increase base font size to 18px / 1.5 lineheight The default pydata-sphinx-theme uses a small base font size (15px) but a large line height (1.65 ratio). For readability, this commit changes the base up to large size (18px) but a slightly smaller height (1.5) since the font is already so readable. --- src/documenteer/assets/rubin-pydata-theme.css | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/documenteer/assets/rubin-pydata-theme.css b/src/documenteer/assets/rubin-pydata-theme.css index bde1cea5..a6a6b1be 100644 --- a/src/documenteer/assets/rubin-pydata-theme.css +++ b/src/documenteer/assets/rubin-pydata-theme.css @@ -69,6 +69,9 @@ html[data-theme='dark'] { --pst-font-family-base: 'Source Sans Pro', var(--pst-font-family-base-system); --pst-font-family-heading: 'Source Sans Pro', var(--pst-font-family-base-system); + + /* Base font size; increased for pydata-sphinx-theme default. */ + font-size: 18px; } html[data-theme='light'] { @@ -84,3 +87,8 @@ html[data-theme='dark'] { --pst-color-text-base: var(--rsd-component-text-color); --pst-color-primary: var(--rsd-color-primary-500); } + +body { + /* Override pydata-sphinx-theme */ + line-height: 1.5; +} From 1cc4cca6d91c7d1ab1f862a8baa6f9858520be55 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 20 Oct 2022 14:19:58 -0400 Subject: [PATCH 2/6] Reduce contrast of tables in dark mode The base CSS didn't actually react to theme, so the light grey (low contrast) lines in light mode became very contrasty lines in dark mode. --- src/documenteer/assets/rubin-pydata-theme.css | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/documenteer/assets/rubin-pydata-theme.css b/src/documenteer/assets/rubin-pydata-theme.css index a6a6b1be..c90efab6 100644 --- a/src/documenteer/assets/rubin-pydata-theme.css +++ b/src/documenteer/assets/rubin-pydata-theme.css @@ -88,6 +88,12 @@ html[data-theme='dark'] { --pst-color-primary: var(--rsd-color-primary-500); } +html[data-theme='dark'] .table td, +html[data-theme='dark'] .table th { + /* Reduce contrast of tables in dark mode. */ + border-top: 1px solid var(--rsd-color-gray-500); +} + body { /* Override pydata-sphinx-theme */ line-height: 1.5; From e210f779fea5aaa7c71d0d2090f371a0b38ef1e5 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 20 Oct 2022 14:28:05 -0400 Subject: [PATCH 3/6] Fix navbar link icon size Somehow in recent pydata-sphinx-theme releases the var(--pst-font-size-icon) was dropped, causing the GitHub icon to be quite small. This fixes that issue, though hopefully we can also fix it upstream. --- src/documenteer/assets/rubin-pydata-theme.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/documenteer/assets/rubin-pydata-theme.css b/src/documenteer/assets/rubin-pydata-theme.css index c90efab6..5f675a7b 100644 --- a/src/documenteer/assets/rubin-pydata-theme.css +++ b/src/documenteer/assets/rubin-pydata-theme.css @@ -98,3 +98,7 @@ body { /* Override pydata-sphinx-theme */ line-height: 1.5; } + +.navbar-nav i { + font-size: var(--pst-font-size-icon); +} From 47d312bda31e9a07479da3069ed007a95cacae31 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 20 Oct 2022 15:24:12 -0400 Subject: [PATCH 4/6] Add customized description for homepage. This will look better than the auto-extracted description. --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index e258d687..43d3efcd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,3 +1,4 @@ +:og:description: Documenteer provides Sphinx extensions, configurations, and tooling for Rubin Observatory documentation projects. :html_theme.sidebar_secondary.remove: ########### From 45fc60cb9047fd536aee38ac7e28e4c515c11d70 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 20 Oct 2022 15:28:30 -0400 Subject: [PATCH 5/6] Update change log for 0.7.0 release --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index db6ba816..626141e2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Change Log -## 0.7.0 (Unreleased) +## 0.7.0 (2022-10-20) - Documenteer provides a new Sphinx configuration profile for general Rubin user guide projects, `documenteer.conf.guide`. This configuration profile features the new [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/), with customizations based on design tokens from the [Rubin Style Dictionary](https://style-dictionary.lsst.io). From d669c9ce04a553f36df2fa90d3b2b65b3ef1c136 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 20 Oct 2022 15:37:39 -0400 Subject: [PATCH 6/6] Update README with new user guides config --- README.md | 52 +++++++--------------------------------------------- 1 file changed, 7 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 2417e981..362a6a36 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ # Documenteer -Documenteer provides tools, extensions, and configurations for Rubin Observatory's Sphinx documentation projects, including [technotes](https://developer.lsst.io/project-docs/technotes.html) and EUPS-packaged stacks (such as the [LSST Science Pipelines](https://pipelines.lsst.io)). +Documenteer provides tools, extensions, and configurations for Rubin Observatory's Sphinx documentation projects, [user guides](https://documenteer.lsst.io/guides/index.html), [technotes](https://developer.lsst.io/project-docs/technotes.html) and EUPS-packaged stacks (such as the [LSST Science Pipelines](https://pipelines.lsst.io)). For more information about Documenteer, see the documentation at https://documenteer.lsst.io. @@ -15,58 +15,20 @@ Browse the [lsst-doc-engineering](https://github.com/topics/lsst-doc-engineering ## Quick installation: -For technical note projects: +For [user guides](https://documenteer.lsst.io/guides/index.html): ```sh pip install "documenteer[technote]" ``` -For the stack projects (such as the [LSST Science Pipelines](https://pipelines.lsst.io)): +For [technical note projects](https://documenteer.lsst.io/technotes/index.html): ```sh -pip install "documenteer[pipelines]" -``` - -## Features - -### Configurations - -Documenteer includes preset configurations for common Rubin Observatory Sphinx projects. -By using Documenteer, you can also ensure that Sphinx extensions required by these configurations are installed. - -From the `conf.py` for technotes: - -```py -from documenteer.conf.technote import * -``` - -From the `conf.py` for a stack package: - -```py -from documenteer.conf.pipelinespkg import * - -project = "example" -html_theme_options['logotext'] = project -html_title = project -html_short_title = project +pip install "documenteer[technote]" ``` -From the `conf.py` for the LSST Science Pipelines documentation: +For the [stack projects](https://documenteer.lsst.io/pipelines/index.html) (such as the [LSST Science Pipelines](https://pipelines.lsst.io)): -```py -from documenteer.conf.pipelines import * +```sh +pip install "documenteer[pipelines]" ``` - -### Command-line tools - -- [package-docs]( https://documenteer.lsst.io/pipelines/package-docs-cli.html) builds documentation for individual packages in the LSST Science Pipelines -- [stack-docs](https://documenteer.lsst.io/pipelines/stack-docs-cli.html) builds documentation for entire Stacks, such as the LSST Science Pipelines -- [refresh-lsst-bib](https://developer.lsst.io/project-docs/technotes.html#using-bibliographies-in-restructuredtext-technotes) maintains Rubin Observatory's common BibTeX files in individual technote repositories - -### Sphinx extensions - -- Roles for linking to LSST documents and Jira tickets -- The `remote-code-block` directive -- The `module-toctree` and `package-toctree` directives for the LSST Science Pipelines documentation -- [Extensions for documenting LSST Science Pipelines tasks](https://documenteer.lsst.io/sphinxext/lssttasks.html) -- Support for LSST BibTeX files with sphinxcontrib-bibtex.