Update documentation for 1.0.0 (#64)

* Update documentation for 1.0.0 * Use uv in readthedocs * Fix docs source dir
JohnPaton · Dec 4, 2024 · 4262da7 · 4262da7
1 parent 12ef986
commit 4262da7
Show file tree

Hide file tree

Showing 24 changed files with 421 additions and 140 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -9,14 +9,15 @@ sphinx:
 
 formats: all
 
+# https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-uv
+
 build:
-  os: ubuntu-20.04
+  os: "ubuntu-22.04"
   tools:
     python: "3.10"
-
-python:
-  install:
-  - method: pip
-    path: .
-    extra_requirements:
-    - docs
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv sync --dev --frozen
+    - uv run -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs/source $READTHEDOCS_OUTPUT/html
diff --git a/docs/Makefile b/docs/Makefile
@@ -11,9 +11,20 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile clean build apidocs
+
+clean:
+	rm -rf build/ source/api
+
+# automatic api docs of airbase
+apidocs:
+	uv run sphinx-apidoc --output-dir ./source/api ../airbase --force --maxdepth 2 --module-first
+
+# Build the Sphinx documentation.
+build: apidocs
+	uv run $(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	uv run @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/docs/source/airbase.rst b/docs/source/airbase.rst
diff --git a/docs/source/api/airbase.airbase.rst b/docs/source/api/airbase.airbase.rst
@@ -0,0 +1,7 @@
+airbase.airbase module
+======================
+
+.. automodule:: airbase.airbase
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.cli.rst b/docs/source/api/airbase.cli.rst
@@ -0,0 +1,7 @@
+airbase.cli module
+==================
+
+.. automodule:: airbase.cli
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.csv_api.client.rst b/docs/source/api/airbase.csv_api.client.rst
@@ -0,0 +1,7 @@
+airbase.csv\_api.client module
+==============================
+
+.. automodule:: airbase.csv_api.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.csv_api.dataset.rst b/docs/source/api/airbase.csv_api.dataset.rst
@@ -0,0 +1,7 @@
+airbase.csv\_api.dataset module
+===============================
+
+.. automodule:: airbase.csv_api.dataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.csv_api.rst b/docs/source/api/airbase.csv_api.rst
@@ -0,0 +1,42 @@
+airbase.csv\_api package
+========================
+
+.. automodule:: airbase.csv_api
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+airbase.csv\_api.client module
+------------------------------
+
+.. automodule:: airbase.csv_api.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+airbase.csv\_api.dataset module
+-------------------------------
+
+.. automodule:: airbase.csv_api.dataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+airbase.csv\_api.session module
+-------------------------------
+
+.. automodule:: airbase.csv_api.session
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+airbase.csv\_api.types module
+-----------------------------
+
+.. automodule:: airbase.csv_api.types
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.csv_api.session.rst b/docs/source/api/airbase.csv_api.session.rst
@@ -0,0 +1,7 @@
+airbase.csv\_api.session module
+===============================
+
+.. automodule:: airbase.csv_api.session
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.csv_api.types.rst b/docs/source/api/airbase.csv_api.types.rst
@@ -0,0 +1,7 @@
+airbase.csv\_api.types module
+=============================
+
+.. automodule:: airbase.csv_api.types
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.parquet_api.client.rst b/docs/source/api/airbase.parquet_api.client.rst
@@ -0,0 +1,7 @@
+airbase.parquet\_api.client module
+==================================
+
+.. automodule:: airbase.parquet_api.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.parquet_api.dataset.rst b/docs/source/api/airbase.parquet_api.dataset.rst
@@ -0,0 +1,7 @@
+airbase.parquet\_api.dataset module
+===================================
+
+.. automodule:: airbase.parquet_api.dataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.parquet_api.rst b/docs/source/api/airbase.parquet_api.rst
@@ -0,0 +1,42 @@
+airbase.parquet\_api package
+============================
+
+.. automodule:: airbase.parquet_api
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+airbase.parquet\_api.client module
+----------------------------------
+
+.. automodule:: airbase.parquet_api.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+airbase.parquet\_api.dataset module
+-----------------------------------
+
+.. automodule:: airbase.parquet_api.dataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+airbase.parquet\_api.session module
+-----------------------------------
+
+.. automodule:: airbase.parquet_api.session
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+airbase.parquet\_api.types module
+---------------------------------
+
+.. automodule:: airbase.parquet_api.types
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.parquet_api.session.rst b/docs/source/api/airbase.parquet_api.session.rst
@@ -0,0 +1,7 @@
+airbase.parquet\_api.session module
+===================================
+
+.. automodule:: airbase.parquet_api.session
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.parquet_api.types.rst b/docs/source/api/airbase.parquet_api.types.rst
@@ -0,0 +1,7 @@
+airbase.parquet\_api.types module
+=================================
+
+.. automodule:: airbase.parquet_api.types
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.rst b/docs/source/api/airbase.rst
@@ -0,0 +1,36 @@
+airbase package
+===============
+
+.. automodule:: airbase
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   airbase.csv_api
+   airbase.parquet_api
+   airbase.summary
+
+Submodules
+----------
+
+airbase.airbase module
+----------------------
+
+.. automodule:: airbase.airbase
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+airbase.cli module
+------------------
+
+.. automodule:: airbase.cli
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.summary.db.rst b/docs/source/api/airbase.summary.db.rst
@@ -0,0 +1,7 @@
+airbase.summary.db module
+=========================
+
+.. automodule:: airbase.summary.db
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/airbase.summary.rst b/docs/source/api/airbase.summary.rst
@@ -0,0 +1,18 @@
+airbase.summary package
+=======================
+
+.. automodule:: airbase.summary
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+airbase.summary.db module
+-------------------------
+
+.. automodule:: airbase.summary.db
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/modules.rst b/docs/source/api/modules.rst
@@ -0,0 +1,7 @@
+airbase
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   airbase
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -27,10 +27,10 @@
 
 # -- Project information -----------------------------------------------------
 
-today = date.today()
+today = date.today().isoformat()
 
 project = "AirBase"
-copyright = f"2019-{today.year}, John Paton"
+copyright = f"2019-{date.today().year}, John Paton"
 author = "John Paton"
 
 # The full version, including alpha/beta/rc tags
@@ -74,7 +74,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -117,7 +117,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.