Merge pull request #25 from MiBiPreT/exorcize_sphinx_and_readthedocs

Add API Reference building to docs

README.dev.md

@@ -81,35 +81,19 @@ You can enable automatic linting with `ruff` on commit by enabling the git hook
 git config --local core.hooksPath .githooks
 ```
 
-## Generating the API docs
+## Testing docs locally
 
+To build the documentation locally, first make sure `mkdocs` and its dependencies are installed:
 ```shell
-cd docs
-make html
+python -m pip install .[doc]
 ```
 
-The documentation will be in `docs/_build/html`
-
-If you do not have `make` use
-
+Then you can build the documentation and serve it locally with
 ```shell
-sphinx-build -b html docs docs/_build/html
+mkdocs serve
 ```
 
-To find undocumented Python objects run
-
-```shell
-cd docs
-make coverage
-cat _build/coverage/python.txt
-```
-
-To [test snippets](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) in documentation run
-
-```shell
-cd docs
-make doctest
-```
+This will return a URL (e.g. `http://127.0.0.1:8000/mibipret/`) where the docs site can be viewed.
 
 ## Versioning
 
@@ -131,10 +115,9 @@ This section describes how to make a release in 3 parts:
 
 ### (1/3) Preparation
 
-1. Update the <CHANGELOG.md> (don't forget to update links at bottom of page)
-2. Verify that the information in [`CITATION.cff`](CITATION.cff) is correct.
-3. Make sure the [version has been updated](#versioning).
-4. Run the unit tests with `pytest -v`
+1. Verify that the information in [`CITATION.cff`](CITATION.cff) is correct.
+1. Make sure the [version has been updated](#versioning).
+1. Run the unit tests with `pytest -v`
 
 ### (2/3) PyPI
 

docs/getting-started/development.md

@@ -0,0 +1,175 @@
+# `mibipret` developer documentation
+
+## Development install
+
+```shell
+# Create a virtual environment, e.g. with
+python -m venv env
+
+# activate virtual environment
+source env/bin/activate
+
+# make sure to have a recent version of pip and setuptools
+python -m pip install --upgrade pip setuptools
+
+# (from the project root directory)
+# install mibipret as an editable package
+python -m pip install --no-cache-dir --editable .
+# install development dependencies
+python -m pip install --no-cache-dir --editable .[dev]
+```
+
+Afterwards check that the install directory is present in the `PATH` environment variable.
+
+## Running the tests
+
+There are two ways to run tests.
+
+The first way requires an activated virtual environment with the development tools installed:
+
+```shell
+pytest -v
+```
+
+The second is to use `tox`, which can be installed separately (e.g. with `pip install tox`), i.e. not necessarily inside the virtual environment you use for installing `mibipret`, but then builds the necessary virtual environments itself by simply running:
+
+```shell
+tox
+```
+
+Testing with `tox` allows for keeping the testing environment separate from your development environment.
+The development environment will typically accumulate (old) packages during development that interfere with testing; this problem is avoided by testing with `tox`.
+
+### Test coverage
+
+In addition to just running the tests to see if they pass, they can be used for coverage statistics, i.e. to determine how much of the package's code is actually executed during tests.
+In an activated virtual environment with the development tools installed, inside the package directory, run:
+
+```shell
+coverage run
+```
+
+This runs tests and stores the result in a `.coverage` file.
+To see the results on the command line, run
+
+```shell
+coverage report
+```
+
+`coverage` can also generate output in HTML and other formats; see `coverage help` for more information.
+
+## Running linters locally
+
+For linting and sorting imports we will use [ruff](https://beta.ruff.rs/docs/). Running the linters requires an 
+activated virtual environment with the development tools installed.
+
+```shell
+# linter
+ruff check .
+
+# linter with automatic fixing
+ruff check . --fix
+```
+
+To fix readability of your code style you can use [yapf](https://github.com/google/yapf).
+
+You can enable automatic linting with `ruff` on commit by enabling the git hook from `.githooks/pre-commit`, like so:
+
+```shell
+git config --local core.hooksPath .githooks
+```
+
+## Testing docs locally
+
+To build the documentation locally, first make sure `mkdocs` and its dependencies are installed:
+```shell
+python -m pip install .[doc]
+```
+
+Then you can build the documentation and serve it locally with
+```shell
+mkdocs serve
+```
+
+This will return a URL (e.g. `http://127.0.0.1:8000/mibipret/`) where the docs site can be viewed.
+
+## Versioning
+
+Bumping the version across all files is done with [bump-my-version](https://github.com/callowayproject/bump-my-version), e.g.
+
+```shell
+bump-my-version major  # bumps from e.g. 0.3.2 to 1.0.0
+bump-my-version minor  # bumps from e.g. 0.3.2 to 0.4.0
+bump-my-version patch  # bumps from e.g. 0.3.2 to 0.3.3
+```
+
+## Making a release
+
+This section describes how to make a release in 3 parts:
+
+1. preparation
+1. making a release on PyPI
+1. making a release on GitHub
+
+### (1/3) Preparation
+
+1. Verify that the information in CITATION.cff is correct.
+1. Make sure the [version has been updated](#versioning).
+1. Run the unit tests with `pytest -v`
+
+### (2/3) PyPI
+
+In a new terminal:
+
+```shell
+# OPTIONAL: prepare a new directory with fresh git clone to ensure the release
+# has the state of origin/main branch
+cd $(mktemp -d mibipret.XXXXXX)
+git clone [email protected]:MiBiPreT/mibipret .
+
+# make sure to have a recent version of pip and the publishing dependencies
+python -m pip install --upgrade pip
+python -m pip install .[publishing]
+
+# create the source distribution and the wheel
+python -m build
+
+# upload to test pypi instance (requires credentials)
+python -m twine upload --repository testpypi dist/*
+```
+
+Visit [https://test.pypi.org/](https://test.pypi.org)
+<!-- [https://test.pypi.org/project/mibipret](https://test.pypi.org/project/mibipret) -->
+and verify that your package was uploaded successfully. Keep the terminal open, we'll need it later.
+
+In a new terminal, without an activated virtual environment or an env directory:
+
+```shell
+cd $(mktemp -d mibipret-test.XXXXXX)
+
+# prepare a clean virtual environment and activate it
+python -m venv env
+source env/bin/activate
+
+# make sure to have a recent version of pip and setuptools
+python -m pip install --upgrade pip
+
+# install from test pypi instance:
+python -m pip -v install --no-cache-dir \
+--index-url https://test.pypi.org/simple/ \
+--extra-index-url https://pypi.org/simple mibipret
+```
+
+Check that the package works as it should when installed from pypitest.
+
+Then upload to pypi.org with:
+
+```shell
+# Back to the first terminal,
+# FINAL STEP: upload to PyPI (requires credentials)
+python -m twine upload dist/*
+```
+
+### (3/3) GitHub
+
+Don't forget to also make a [release on GitHub](https://github.com/MiBiPreT/mibipret/releases/new). If your repository uses the GitHub-Zenodo integration this will also trigger Zenodo into making a snapshot of your repository and sticking a DOI on it.

docs/index.md

@@ -5,10 +5,10 @@ A Python package for prediction and analysis in Microbiome based Remediation. De
 
 ## Installation
 
-To install anatrans from GitHub repository, do:
+To install mibipret from GitHub repository, do:
 
 ```console
-git clone [email protected]:MiBiPreT/anatrans.git
-cd anatrans
-python -m pip install .
+git clone [email protected]:MiBiPreT/mibipret.git
+cd mibipret
+python -m pip mibipret .
 ```

docs/reference/reference.md

@@ -0,0 +1,3 @@
+# `mibipret` API reference
+
+::: mibipret

mibipret/__init__.py

@@ -1,4 +1,4 @@
-"""Documentation about anatrans."""
+"""Documentation about mibipret."""
 import logging
 
 logging.getLogger(__name__).addHandler(logging.NullHandler())

mibipret/my_module.py

@@ -1,4 +1,4 @@
-"""Documentation about the anatrans module."""
+"""Documentation about the mibipret module."""
 
 
 # FIXME: put actual code here
@@ -19,7 +19,7 @@ def hello(name):
     Example:
         This function can be called with `Jane Smith` as argument using
 
-        >>> from anatrans.my_module import hello
+        >>> from mibipret.my_module import hello
         >>> hello('Jane Smith')
         'Hello Jane Smith!'
 

mkdocs.yml

@@ -7,6 +7,13 @@ repo_url: https://github.com/MiBiPreT/mibipret
 edit_uri: "edit/main/docs/"
 copyright: Copyright © 2024 Alraune Zech, Sona Aseyednezhad, Robin Richardson, Jaro Camphuijsen
 
+nav:
+  - Getting started:
+    - Getting started: index.md
+    - Development: getting-started/development.md
+  - API Reference:
+    - Reference: reference/reference.md
+
 theme:
   name: "material"
   favicon: assets/icon.png
@@ -53,9 +60,8 @@ plugins:
       python:
         rendering:
           show_source: true
-    watch:
-      - mibipret
-
+        options:
+          show_submodules: true
 
 # Styled blocks: https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types
 markdown_extensions:
@@ -81,11 +87,5 @@ extra_javascript:
 
 extra:
   social:
-#    - icon: fontawesome/brands/python
-#      link: https://pypi.org/project/nanopub
     - icon: fontawesome/brands/github
-      link: https://github.com/mibipret
-    # - icon: fontawesome/brands/docker
-    #   link: https://github.com/orgs/fair-workflows/packages
-    # - icon: fontawesome/brands/twitter
-    #   link: https://twitter.com/
+      link: https://github.com/MiBiPreT/mibipret

pyproject.toml

@@ -44,11 +44,7 @@ dev = [
     "pytest",
     "pytest-cov",
     "ruff",
-    "sphinx",
-    "sphinx_rtd_theme",
-    "sphinx-autoapi",
     "tox",
-    "myst_parser",
 ]
 publishing = [
     "build",