From c493026978c0eb34980085a49ae24de1a51a8ce7 Mon Sep 17 00:00:00 2001 From: Troy Raen Date: Fri, 28 Jun 2024 20:25:33 -0700 Subject: [PATCH] Minor documentation updates (#38) * add doc build-docs-sphinx * move docs for-developers under main * minor docs updates * change toctree maxdepth * update CHANGELOG for v0.3.3 release --- CHANGELOG.md | 14 +++++--- docs/source/index.rst | 36 ++++++++----------- docs/source/main/faq/index.rst | 2 +- .../main/for-developers/build-docs-sphinx.md | 31 ++++++++++++++++ docs/source/main/for-developers/index.rst | 10 ++++++ .../manage-dependencies-poetry.md | 0 .../for-developers/release-new-version.md | 1 + .../for-developers/setup-environment.md | 0 .../main/one-time-setup/authentication.rst | 2 +- docs/source/main/one-time-setup/index.rst | 2 +- 10 files changed, 69 insertions(+), 29 deletions(-) create mode 100644 docs/source/main/for-developers/build-docs-sphinx.md create mode 100644 docs/source/main/for-developers/index.rst rename docs/source/{ => main}/for-developers/manage-dependencies-poetry.md (100%) rename docs/source/{ => main}/for-developers/release-new-version.md (91%) rename docs/source/{ => main}/for-developers/setup-environment.md (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index c169e8a..425f3aa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) (none) -## \[0.3.2\] - 2024-06-28 +## \[v0.3.3\] - 2024-06-28 + +### Changed + +- Minor documentation updates. + +## \[v0.3.2\] - 2024-06-28 ### Added @@ -23,7 +29,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - Major documentation reorganization and updates. - Rename the PubSub.Consumer parameter batch_maxwait -> batch_max_wait_between_messages for clarity. -## \[0.3.1\] - 2024-06-26 +## \[v0.3.1\] - 2024-06-26 ### Added @@ -42,7 +48,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - pittgoogle_env.yml file -## \[0.3.0\] - 2024-06-08 +## \[v0.3.0\] - 2024-06-08 ### Added @@ -65,7 +71,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - v0.1 `bigquery` functions. - Setup and requirements files that are no longer needed after switching away from Read The Docs. -## \[0.2.0\] - 2023-07-02 +## \[v0.2.0\] - 2023-07-02 ### Added diff --git a/docs/source/index.rst b/docs/source/index.rst index 2711371..872d057 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,28 +3,29 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +pittgoogle-client +================= + +`pittgoogle-client` is a python library for accessing astronomy data served by +`Pitt-Google Alert Broker `__. +Tutorials and examples can be found at +`Pitt-Google User Demos `__. +If you run into trouble, please +`open an Issue `__. + .. toctree:: - :maxdepth: 3 - :hidden: + :caption: Overview + :maxdepth: 1 main/listings Install
main/one-time-setup/index main/faq/index - -.. toctree:: - :caption: For Developers - :maxdepth: 3 - :hidden: - - for-developers/setup-environment - for-developers/manage-dependencies-poetry - for-developers/release-new-version + main/for-developers/index .. toctree:: :caption: API Reference - :maxdepth: 3 - :hidden: + :maxdepth: 1 api-reference/auth api-reference/bigquery @@ -32,12 +33,3 @@ api-reference/pubsub api-reference/registry api-reference/utils - -pittgoogle-client -================= - -`pittgoogle-client` is a python library for accessing astronomy data served by -`Pitt-Google Alert Broker `__. - -If you run into trouble, please -`open an Issue `__. diff --git a/docs/source/main/faq/index.rst b/docs/source/main/faq/index.rst index 0745f3d..03be330 100644 --- a/docs/source/main/faq/index.rst +++ b/docs/source/main/faq/index.rst @@ -2,7 +2,7 @@ Frequently Asked Questions ============================================== .. toctree:: - :maxdepth: 3 + :maxdepth: 1 cost find-project-id diff --git a/docs/source/main/for-developers/build-docs-sphinx.md b/docs/source/main/for-developers/build-docs-sphinx.md new file mode 100644 index 0000000..fc137bf --- /dev/null +++ b/docs/source/main/for-developers/build-docs-sphinx.md @@ -0,0 +1,31 @@ +# Build Documentation with Sphinx + +This page describes how to build documentation locally for testing. +This is not always needed. +Our published documentation is built and released automatically when a +[new package version](release-new-version.md) is released. +In addition, every PR triggers automatic testing of the documentation build. +However, those GitHub builds can take awhile and there doesn't seem to be an easy way to actually +view the built documentation. +For those reasons, it is sometimes helpful to be able to build the documentation locally. + +Follow the setup steps in [Managing Dependencies with Poetry](manage-dependencies-poetry.md) to +create a conda environment with Poetry installed. Then: + +```bash +# Install pittgoogle dependencies, including those in the "docs" group. +poetry install --with=docs +``` + +Now, `cd` to the docs directory and run `make`: + +```bash +cd docs # assuming we started in the repo root directory + +# Build the documentation +make clean +make html +``` + +This should have created a file at `docs/build/html/index.html`. +Open it in a browser to view the built documentation. diff --git a/docs/source/main/for-developers/index.rst b/docs/source/main/for-developers/index.rst new file mode 100644 index 0000000..0247952 --- /dev/null +++ b/docs/source/main/for-developers/index.rst @@ -0,0 +1,10 @@ +For Developers +================= + +.. toctree:: + :maxdepth: 1 + + setup-environment + manage-dependencies-poetry + build-docs-sphinx + release-new-version diff --git a/docs/source/for-developers/manage-dependencies-poetry.md b/docs/source/main/for-developers/manage-dependencies-poetry.md similarity index 100% rename from docs/source/for-developers/manage-dependencies-poetry.md rename to docs/source/main/for-developers/manage-dependencies-poetry.md diff --git a/docs/source/for-developers/release-new-version.md b/docs/source/main/for-developers/release-new-version.md similarity index 91% rename from docs/source/for-developers/release-new-version.md rename to docs/source/main/for-developers/release-new-version.md index ddc60ed..304ebd6 100644 --- a/docs/source/for-developers/release-new-version.md +++ b/docs/source/main/for-developers/release-new-version.md @@ -11,6 +11,7 @@ When you are ready to release a new version of `pittgoogle-client`, publish to P - Under "Choose a tag", enter the version tag as "v" followed by the release version ([semantic versioning](https://semver.org/) MAJOR.MINOR.PATCH). - Enter the same tag for the release title. + - Under "Write", paste in the relevant section of CHANGELOG.md describing the release. - Click "Publish release". Completing step 3 will: diff --git a/docs/source/for-developers/setup-environment.md b/docs/source/main/for-developers/setup-environment.md similarity index 100% rename from docs/source/for-developers/setup-environment.md rename to docs/source/main/for-developers/setup-environment.md diff --git a/docs/source/main/one-time-setup/authentication.rst b/docs/source/main/one-time-setup/authentication.rst index eba32f5..748e02c 100644 --- a/docs/source/main/one-time-setup/authentication.rst +++ b/docs/source/main/one-time-setup/authentication.rst @@ -7,7 +7,7 @@ Authentication for API calls is obtained directly from Google Cloud. Two options are implemented in pittgoogle. Complete at least one: .. toctree:: - :maxdepth: 3 + :maxdepth: 1 Service Account (recommended) OAuth2 diff --git a/docs/source/main/one-time-setup/index.rst b/docs/source/main/one-time-setup/index.rst index db15c58..2fd597a 100644 --- a/docs/source/main/one-time-setup/index.rst +++ b/docs/source/main/one-time-setup/index.rst @@ -6,7 +6,7 @@ One-Time Setup Using pittgoogle-client to interact with cloud resources requires the following one-time setup tasks: .. toctree:: - :maxdepth: 3 + :maxdepth: 1 Install pittgoogle-client Setup a Google Cloud Project