Merge pull request #38 from lsst-dm/tickets/DM-46368

DM-46368: Add support for building an LTD documentation site

.github/workflows/docs.yaml

@@ -0,0 +1,57 @@
+name: Build and upload documentation
+
+"on":
+  merge_group: {}
+  pull_request: {}
+  push:
+    branches-ignore:
+      # These should always correspond to pull requests, so ignore them for
+      # the push trigger and let them be triggered by the pull_request
+      # trigger, avoiding running the workflow twice.  This is a minor
+      # optimization so there's no need to ensure this is comprehensive.
+      - "dependabot/**"
+      - "gh-readonly-queue/**"
+      - "renovate/**"
+      - "tickets/**"
+      - "u/**"
+  release:
+    types: [published]
+
+jobs:
+  docs:
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history for setuptools_scm
+
+      - name: Install Graphviz
+        run: sudo apt-get install graphviz
+
+      - name: Run tox
+        uses: lsst-sqre/run-tox@v1
+        with:
+          python-version: "3.11"
+          tox-envs: "docs"
+          # Add docs-linkcheck when the docs and PyPI package are published
+          # tox-envs: "docs,docs-linkcheck"
+          tox-plugins: tox-uv
+
+      # Only attempt documentation uploads for tagged releases and pull
+      # requests from ticket branches in the same repository.  This avoids
+      # version clutter in the docs and failures when a PR doesn't have access
+      # to secrets.
+      - name: Upload to LSST the Docs
+        uses: lsst-sqre/ltd-upload@v1
+        with:
+          project: "consdb"
+          dir: "doc/_build/html"
+          username: ${{ secrets.LTD_USERNAME }}
+          password: ${{ secrets.LTD_PASSWORD }}
+        if: >
+          github.event_name != 'merge_group'
+          && (github.event_name != 'pull_request'
+              || startsWith(github.head_ref, 'tickets/'))

.gitignore

@@ -14,6 +14,9 @@ config.log
 version.py
 bin/
 
+# pip build
+build/
+
 # Pytest
 tests/.tests
 pytest_session.txt
@@ -27,5 +30,6 @@ htmlcov
 .mypy.ini
 
 # environment
+.tox
 .venv
 .vscode

doc/conf.py

@@ -1,13 +1,6 @@
 """Sphinx configuration file for an LSST stack package.
 
-This configuration only affects single-package Sphinx documentation builds.
-For more information, see:
-https://developer.lsst.io/stack/building-single-package-docs.html
+This configuration only affects single-package Sphinx documenation builds.
 """
 
-from documenteer.conf.pipelinespkg import *  # type: ignore # noqa
-
-project = "consdb"
-html_theme_options["logotext"] = project  # type: ignore # noqa
-html_title = project
-html_short_title = project
+from documenteer.conf.guide import *  # noqa: F403,F401

doc/documenteer.toml

@@ -0,0 +1,11 @@
+[project]
+title = "ConsDB"
+copyright = "GNU General Public License v3"
+
+[project.python]
+package = "consdb"
+
+[sphinx]
+disable_primary_sidebars = [
+    "index"
+]

doc/index.rst

@@ -1,51 +1,16 @@
-.. py:currentmodule:: lsst.consdb
+:html_theme.sidebar_secondary.remove:
 
-.. _lsst.consdb:
-
-###########
-lsst.consdb
-###########
-
-.. Paragraph that describes what this Python module does and links to related modules and frameworks.
-
-.. .. _lsst.consdb-using:
-
-.. Using lsst.consdb
-.. =================
-
-.. toctree linking to topics related to using the module's APIs.
-
-.. .. toctree::
-..    :maxdepth: 1
-
-.. _lsst.consdb-contributing:
-
-Contributing
-============
+ConsDB
+======
 
 ``lsst.consdb`` is developed at https://github.com/lsst-dm/consdb.
 You can find Jira issues for this module under the `consdb <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20consdb>`_ component.
 
-.. If there are topics related to developing this module (rather than using it), link to this from a toctree placed here.
-
-.. .. toctree::
-..    :maxdepth: 1
-
-.. .. _lsst.consdb-scripts:
-
-.. Script reference
-.. ================
-
-.. .. TODO: Add an item to this toctree for each script reference topic in the scripts subdirectory.
-
-.. .. toctree::
-..    :maxdepth: 1
-
-.. .. _lsst.consdb-pyapi:
+#############
+Documentation
+#############
 
-Python API reference
-====================
+.. toctree::
+    :maxdepth: 1
 
-.. automodapi:: lsst.consdb
-   :no-main-docstr:
-   :no-inheritance-diagram:
+    user-guide/index

doc/user-guide/index.rst

@@ -0,0 +1,8 @@
+##########
+User Guide
+##########
+
+.. toctree::
+   :maxdepth: 1
+
+   installation

doc/user-guide/installation.rst

@@ -0,0 +1,5 @@
+############
+Installation
+############
+
+installation instructions go here

pyproject.toml

@@ -8,9 +8,12 @@ description = "consdb provides support for the Consolidated Database for the `Ve
 license = { text = "GPL" }
 dependencies = ["fastapi", "requests", "sqlalchemy", "astropy"]
 readme = "README.rst"
-urls = { documentation = "https://consdb.lsst.io", source_code = "https://github.com/lsst-dm/consdb"}
 dynamic = ["version"]
 
+[project.urls]
+Homepage = "https://consdb.lsst.io"
+Source = "https://github.com/lsst-dm/consdb"
+
 [tool.black]
 line-length = 110
 target-version = ["py311"]
@@ -38,4 +41,7 @@ log_level = "DEBUG"
 asyncio_mode = "auto"
 
 [project.optional-dependencies]
-dev = ["pytest"]
+test = ["pytest"]
+dev = [
+    "documenteer[guide] < 2",
+]

tox.ini

@@ -0,0 +1,47 @@
+[tox]
+envlist = py,coverage-report,typing,lint,docs,docs-linkcheck
+isolated_build = True
+
+[testenv]
+description = Run pytest against {envname}.
+extras =
+    dev
+
+[testenv:py]
+description = Run pytest
+commands =
+    coverage run -m pytest {posargs}
+
+[testenv:coverage-report]
+description = Compile coverage from each test run.
+skip_install = true
+deps = coverage[toml]>=5.0.2
+depends =
+    py
+commands =
+    coverage combine
+    coverage report
+
+[testenv:typing]
+description = Run mypy.
+commands =
+    mypy src/example tests
+
+[testenv:lint]
+description = Lint codebase by running pre-commit (Black, isort, Flake8).
+skip_install = true
+deps =
+    pre-commit
+commands = pre-commit run --all-files
+
+[testenv:docs]
+description = Build documentation (HTML) with Sphinx.
+commands =
+    sphinx-build --keep-going -n -W -T -b html -d {envtmpdir}/doctrees doc doc/_build/html
+
+[testenv:docs-linkcheck]
+description = Check links in the documentation.
+allowlist_externals =
+    make
+commands =
+    make linkcheck