Merge pull request #141 from lsst-sqre/tickets/DM-36665

DM-36665: Improve readability of documentation

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).

README.md

@@ -7,66 +7,28 @@
 
 # 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.
 
 Browse the [lsst-doc-engineering](https://github.com/topics/lsst-doc-engineering) GitHub topic for more Rubin Observatory documentation engineering projects.
 
 ## 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.

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:
 
 ###########

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,18 @@ html[data-theme='dark'] {
   --pst-color-text-base: var(--rsd-component-text-color);
   --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;
+}
+
+.navbar-nav i {
+  font-size: var(--pst-font-size-icon);
+}