diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..75a28455 --- /dev/null +++ b/.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/')) diff --git a/.gitignore b/.gitignore index fc9832de..c292f5a2 100644 --- a/.gitignore +++ b/.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 diff --git a/doc/conf.py b/doc/conf.py index 923b74cd..92ef9848 100644 --- a/doc/conf.py +++ b/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 diff --git a/doc/documenteer.toml b/doc/documenteer.toml new file mode 100644 index 00000000..5706657d --- /dev/null +++ b/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" +] diff --git a/doc/index.rst b/doc/index.rst index 1cfdfb24..4d19b12f 100644 --- a/doc/index.rst +++ b/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 `_ 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 diff --git a/doc/user-guide/index.rst b/doc/user-guide/index.rst new file mode 100644 index 00000000..a72e2392 --- /dev/null +++ b/doc/user-guide/index.rst @@ -0,0 +1,8 @@ +########## +User Guide +########## + +.. toctree:: + :maxdepth: 1 + + installation diff --git a/doc/user-guide/installation.rst b/doc/user-guide/installation.rst new file mode 100644 index 00000000..e58032fe --- /dev/null +++ b/doc/user-guide/installation.rst @@ -0,0 +1,5 @@ +############ +Installation +############ + +installation instructions go here diff --git a/pyproject.toml b/pyproject.toml index 8cdc7cd5..303d77c3 100644 --- a/pyproject.toml +++ b/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", +] diff --git a/tox.ini b/tox.ini new file mode 100644 index 00000000..2b7abc74 --- /dev/null +++ b/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