Add documentation build scripts

name: Deploy Sphinx documentation to Pages

on:

  push:

    tags: ["v[0-9]+.[0-9]+.[0-9]+"]

jobs:

  build:

    runs-on: ubuntu-latest

    steps:

    - uses: actions/checkout@v3

    - uses: actions/setup-python@v3

    - name: Install dependencies

      run: pip install .[docs]

    - name: Sphinx build

      run: make -C doc html BUILDOUT=../_site

    - name: Upload artifact

      uses: actions/upload-pages-artifact@v3

  deploy:

    runs-on: ubuntu-latest

    needs: build

    environment:

      name: github-pages

      url: ${{ steps.deployment.outputs.page_url }}

    permissions:

      pages: write

      id-token: write

    steps:

    - name: Deploy to GitHub Pages

      id: deployment

      uses: actions/deploy-pages@v4

[lint.per-file-ignores]

"test*" = ["D1"]

"doc/*" = ["D"]

*.rst

SPHINXBUILD = sphinx-build

SPHINXOPTS = -j auto

SPHINXAPIDOC = sphinx-apidoc

SPHINXAPIDOCOPTS = --separate

BUILDDIR = build

# Alternatives: html dirhtml singlehtml

HTML_BUILDER = html

# Values above this line may be modified from cmdline

# ======

PKG_NAMESPACE = kodo

PKG_NAME = quantities

BUILD_SRC = Makefile conf.py

SPHINX_SRC = $(BUILD_SRC) index.md $(PKG_NAMESPACE).$(PKG_NAME).rst

#SPHINX_SRC += **additional .md files**

APIDOC_SRC := $(BUILD_SRC)

APIDOC_SRC += $(wildcard ../$(PKG_NAMESPACE)/$(PKG_NAME)/*.py)

APIDOC_SRC += $(wildcard templates/apidoc/*.rst_t)

BUILDOUT = $(@D)

.PHONY: default all

default:

.PHONY all default: html

html: BUILDER=$(HTML_BUILDER)

html: doctest $(BUILDDIR)/html/index.html

.PHONY all: man

man: BUILDER=man

man: doctest $(BUILDDIR)/man/$(PKG_NAMESPACE)$(PKG_NAMESPACE)$(PKG_NAME).1

.PHONY all: text

text: BUILDER=text

text: doctest $(BUILDDIR)/text/index.txt

.PHONY: doctest

doctest: BUILDER=doctest

doctest: $(BUILDDIR)/doctest/output.txt $(APIDOC_SRC)

.PHONY: clean

clean:

	-rm -rf $(BUILDDIR)

	-rm $(PKG_NAMESPACE).*

$(PKG_NAMESPACE).$(PKG_NAME).rst: $(BUILD_SRC) $(APIDOC_SRC)

	$(SPHINXAPIDOC) $(SPHINXAPIDOCOPTS) --implicit-namespaces -MTft templates/apidoc -o . ../$(PKG_NAMESPACE)

	@rm $(PKG_NAMESPACE).rst

	@touch $@

$(BUILDDIR)/%: $(BUILD_SRC) $(SPHINX_SRC) | $(BUILDDIR)

	$(SPHINXBUILD) -ab $(BUILDER) $(SPHINXOPTS) . $(BUILDOUT)

$(BUILDDIR):

	mkdir -p $@

import sys

from pathlib import Path

project = "kodo.quantities"

highlight_language = "python3"

add_module_names = False

html_theme = "sphinx_rtd_theme"

extensions = [

	"sphinx.ext.autodoc",

	"sphinx.ext.doctest",

	"sphinx.ext.viewcode",

	"sphinx.ext.intersphinx",

	"myst_parser",

	"kodo.plugins.sphinx_docstrings",

]

myst_enable_extensions = [

	"substitution",

]

doc_dir = Path(__file__).parent.absolute()

sys.path.insert(0, str(doc_dir))

sys.path.insert(0, str(doc_dir.parent))

autoclass_content = "class"

autodoc_class_signature = "mixed"

autodoc_member_order = "bysource"

autodoc_typehints = "both"

autodoc_typehints_description_target = "documented"

autodoc_typehints_format = "fully-qualified"

autodoc_inherit_docstring = True

doctest_test_doctest_blocks = "default"

myst_heading_anchors = 3

myst_substitutions = {}

intersphinx_mapping = {

	"python": ("https://docs.python.org/3", None),

}

doctest_global_setup = """

from kodo.quantities import *

from unittest.mock import patch

patch("time.sleep", return_value=None).start()

"""