Add sphinx-apipages code and docs (#1)

* Add apipages_hidden_methods config value

* DOC; add first files

* Use autosummary_context instead of html_context

* Fix class template

* Add usage section

* Add audb example API documentation

* Add docs/requirements.txt

* Add gitignore

* Add Github Actions

* Use Python 3.10 for pre-commit

* Fix triggering of autosummary

* Clean up config

* Fix usage documentation by excluding autosummary

* Move extension from builder- to config-inited

* Extend README

* Disable doc link check

.github/workflows/doc.yml

@@ -0,0 +1,40 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ ubuntu-latest ]
+        python-version: [ '3.10' ]
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install package
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+
+    # DOCS
+    - name: Install docs requirements
+      run: pip install -r docs/requirements.txt
+
+    - name: Test building documentation
+      run: python -m sphinx docs/ docs/_build/ -b html -W
+
+    # Don't check links until we have a release
+    #- name: Check links in documentation
+    #  run: python -m sphinx docs/ docs/_build/ -b linkcheck -W

.github/workflows/linter.yml

@@ -0,0 +1,29 @@
+name: Linter
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: Install pre-commit hooks
+      run: |
+        pip install pre-commit
+        pre-commit install --install-hooks
+
+    - name: Code style check via pre-commit
+      run: |
+        pre-commit run --all-files

.github/workflows/publish.yml

@@ -0,0 +1,70 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+      id-token: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 2
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build virtualenv
+    # PyPI package
+    - name: Build Python package
+      run: python -m build
+    - name: Publish Python package to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+    # Docuemntation
+    - name: Install doc dependencies
+      run: |
+        pip install -r requirements.txt
+        pip install -r docs/requirements.txt
+    - name: Build documentation
+      run: |
+        python -m sphinx docs/ docs/_build/ -b html
+    - name: Deploy documentation to Github pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build
+    # Github release
+    - name: Read CHANGELOG
+      id: changelog
+      run: |
+        # Get bullet points from last CHANGELOG entry
+        CHANGELOG=$(git diff -U0 HEAD^ HEAD | grep '^[+][\* ]' | sed 's/\+//')
+        echo "Got changelog: $CHANGELOG"
+        # Support for multiline, see
+        # https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings
+        {
+          echo 'body<<EOF'
+          echo "$CHANGELOG"
+          echo EOF
+        } >> "$GITHUB_OUTPUT"
+    - name: Create release on Github
+      id: create_release
+      uses: softprops/action-gh-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        tag_name: ${{ github.ref }}
+        name: Release ${{ github.ref_name }}
+        body: ${{ steps.changelog.outputs.body }}

.gitignore

@@ -0,0 +1,11 @@
+__pycache__
+*.egg-info/
+.eggs/
+build/
+dist/
+.idea/
+venv/
+.coverage*
+__init__.pyc
+coverage.xml
+docs/api/

.pre-commit-config.yaml

@@ -9,7 +9,7 @@
 #
 #
 default_language_version:
-  python: python3.8
+  python: python3.10
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit

CHANGELOG.rst

@@ -0,0 +1,19 @@
+Changelog
+=========
+
+All notable changes to this project will be documented in this file.
+
+The format is based on `Keep a Changelog`_,
+and this project adheres to `Semantic Versioning`_.
+
+
+Version 0.1.0 (2024-XX-XX)
+---------------------------
+
+* Added: initial release (to be done)
+
+
+.. _Keep a Changelog:
+    https://keepachangelog.com/en/1.0.0/
+.. _Semantic Versioning:
+    https://semver.org/spec/v2.0.0.html

CONTRIBUTING.rst

@@ -0,0 +1,126 @@
+Contributing
+============
+
+If you find errors,
+omissions,
+inconsistencies,
+or other things
+that need improvement,
+please create an issue_.
+If you would like to add new functionality
+create a `merge request`_ .
+Contributions are always welcome!
+
+.. _issue: https://gitlab.audeering.com/tools/sphinx-apipages/issues/new?issue%5BD=
+.. _merge request: https://gitlab.audeering.com/tools/sphinx-apipages/-/merge_requests
+
+
+Development Installation
+------------------------
+
+Instead of installing the latest release from PyPI with pip_,
+you should get the newest development version from Github_::
+
+    git clone [email protected]:audeering/sphinx-apipages.git
+    cd sphinx-apipages
+    # Use virtual environment
+    pip install -r requirements.txt
+
+.. _pip: https://pip.pypa.io
+.. _Github: https://github.com/audeering/sphinx-apipages/
+
+This way,
+your installation always stays up-to-date,
+even if you pull new changes
+from the Gitlab repository.
+
+
+Coding Convention
+-----------------
+
+We follow the PEP8_ convention for Python code
+and use ruff_ as a linter and code formatter.
+In addition,
+we check for common spelling errors with codespell_.
+Both tools and possible exceptions
+are defined in :file:`pyproject.toml`.
+
+The checks are executed in the CI using `pre-commit`_.
+You can enable those checks locally by executing::
+
+    pip install pre-commit  # consider system wide installation
+    pre-commit install
+    pre-commit run --all-files
+
+Afterwards ruff_ and codespell_ are executed
+every time you create a commit.
+
+You can also install ruff_ and codespell_
+and call it directly::
+
+    pip install ruff codespell  # consider system wide installation
+    ruff check --fix .  # lint all Python files, and fix any fixable errors
+    ruff format .  # format code of all Python files
+    codespell
+
+It can be restricted to specific folders::
+
+    ruff check sphinx-apipages/ tests/
+    codespell sphinx-apipages/ tests/
+
+
+.. _codespell: https://github.com/codespell-project/codespell/
+.. _PEP8: http://www.python.org/dev/peps/pep-0008/
+.. _pre-commit: https://pre-commit.com
+.. _ruff: https://beta.ruff.rs
+
+
+Building the Documentation
+--------------------------
+
+If you make changes to the documentation, you can re-create the HTML pages
+using Sphinx_.
+You can install it and a few other necessary packages with::
+
+    pip install -r requirements.txt
+    pip install -r docs/requirements.txt
+
+To create the HTML pages, use::
+
+	python -m sphinx docs/ build/sphinx/html -b html
+
+The generated files will be available in the directory ``build/sphinx/html/``.
+
+It is also possible to automatically check if all links are still valid::
+
+    python -m sphinx docs/ build/sphinx/linkcheck -b linkcheck
+
+.. _Sphinx: http://sphinx-doc.org
+
+
+Running the Tests
+-----------------
+
+You'll need pytest_ for that.
+It can be installed with::
+
+    pip install -r tests/requirements.txt
+
+To execute the tests, simply run::
+
+    python -m pytest
+
+pytest_ is configured inside :file:`pyproject.toml`.
+
+.. _pytest: https://pytest.org
+
+
+Creating a New Release
+----------------------
+
+New releases are made using the following steps:
+
+#. Update ``CHANGELOG.rst``
+#. Commit those changes as "Release X.Y.Z" with a pull request
+#. Create an (annotated) tag with ``git tag -a vX.Y.Z``
+#. Push the commit and the tag to Gitlab

README.rst

@@ -2,13 +2,17 @@
 sphinx-apipages
 ===============
 
-**sphinx-apipages** is a sphinx_ extension,
-that splits your API documentation
-into several sub-pages.
+**sphinx-apipages** is a sphinx_ extension
+for API documentation.
+It uses the autosummary_ and autodoc_ directives,
+and creates sub-pages
+for each function and class.
 
 Have a look at the installation_ and usage_ instructions.
 
 
+.. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+.. _autosummary: https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
 .. _installation: https://audeering.github.io/sphinx-apipages/install.html
 .. _sphinx: https://www.sphinx-doc.org/en/master/
 .. _usage: https://audeering.github.io/sphinx-apipages/usage.html

docs/api-src/audb.rst

@@ -0,0 +1,53 @@
+.. _audb:
+
+audb
+====
+
+Example API documentation,
+extracted from :mod:`audb`.
+
+The corresponding source file
+``docs/api-src/audb.rst``
+contains
+(without this text):
+
+.. code-block:: rst
+
+    audb
+    ====
+
+    .. automodule:: audb
+
+    .. rubric:: Classes
+
+    .. autosummary::
+        :toctree:
+        :nosignatures:
+
+        Repository
+        
+    .. rubric:: Functions
+
+    .. autosummary::
+        :toctree:
+        :nosignatures:
+
+        repository
+
+.. automodule:: audb
+
+.. rubric:: Classes
+
+.. autosummary::
+    :toctree:
+    :nosignatures:
+
+    Repository
+
+.. rubric:: Functions
+
+.. autosummary::
+    :toctree:
+    :nosignatures:
+
+    repository

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGELOG.rst