From 53c96a2ea583a41a3bd8938f23ffe0d2eae64a0b Mon Sep 17 00:00:00 2001 From: Jonathan Harker Date: Thu, 26 Sep 2024 17:29:50 +1200 Subject: [PATCH] Add documentation by Sphinx --- .gitignore | 3 ++ docs/Makefile | 20 +++++++++++ docs/source/conf.py | 71 ++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 27 +++++++++++++++ docs/source/modules.rst | 7 ++++ docs/source/readme.md | 4 +++ docs/source/setclass.rst | 18 ++++++++++ requirements-dev.txt | 5 +++ setclass/setclass.py | 3 +- 9 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 docs/Makefile create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/modules.rst create mode 100644 docs/source/readme.md create mode 100644 docs/source/setclass.rst diff --git a/.gitignore b/.gitignore index 0df55ff..2f10960 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,6 @@ __pycache__ # Virtual environments /venv/ /.venv/ + +# Documentation +/docs/build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# 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) diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..5fbe555 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,71 @@ +""" +Configuration file for the Sphinx documentation builder. +For the full list of built-in configuration values, see the +[documentation](https://www.sphinx-doc.org/en/master/usage/configuration.html). +""" + +import sys +import sphinx_rtd_theme +from pathlib import Path + + +project_root = Path(__file__).resolve().parent.parent +source_root = project_root / 'setclass' +doc_root = project_root / 'docs' / 'source' +sys.path.insert(0, source_root) + + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Setclass' +copyright = '2024, Jonathan Harker' +author = 'Jonathan Harker' +release = '0.1' + + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', + 'sphinx.ext.mathjax', + 'sphinx_rtd_theme', + 'myst_parser', +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3.12', None), +} + +templates_path = ['_templates'] + +exclude_patterns = [ + '_build', + '.DS_Store', + '.pytest_cache', + '.tox', + '.venv', +] + +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', + '.txt': 'markdown', +} + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output +html_theme = 'sphinx_rtd_theme' +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_theme_options = { + 'display_version': False, + 'navigation_depth': 2, + 'prev_next_buttons_location': 'None' +} + +html_static_path = ['_static'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..fbf9011 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,27 @@ +.. Setclass documentation master file, created by + sphinx-quickstart on Sat Sep 21 12:30:24 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Setclass documentation +====================== + +.. include:: readme.md + +.. contents:: + :depth: 2 + :local: + +.. toctree:: + :maxdepth: 2 + :includehidden: + + modules.rst + setclass.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..23a0b74 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +setclass +======== + +.. toctree:: + :maxdepth: 4 + + setclass diff --git a/docs/source/readme.md b/docs/source/readme.md new file mode 100644 index 0000000..e3059a0 --- /dev/null +++ b/docs/source/readme.md @@ -0,0 +1,4 @@ +README: + +```{include} ../../README.md +``` diff --git a/docs/source/setclass.rst b/docs/source/setclass.rst new file mode 100644 index 0000000..ed60012 --- /dev/null +++ b/docs/source/setclass.rst @@ -0,0 +1,18 @@ +setclass package +================ + +setclass module +--------------- + +.. automodule:: setclass.setclass + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: setclass + :members: + :undoc-members: + :show-inheritance: diff --git a/requirements-dev.txt b/requirements-dev.txt index 1e67d9d..e60b3ed 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -11,3 +11,8 @@ pre-commit pytest pytest-cov tox + +# Documentation +sphinx +sphinx_rtd_theme +myst-parser diff --git a/setclass/setclass.py b/setclass/setclass.py index d58f34d..aeead6b 100644 --- a/setclass/setclass.py +++ b/setclass/setclass.py @@ -11,6 +11,7 @@ class cache_property: def __init__(self, function): self.function = function self.name = function.__name__ + self.__doc__ = function.__doc__ def __get__(self, obj, type=None) -> object: obj.__dict__[self.name] = self.function(obj) @@ -98,7 +99,7 @@ class SetClass(list): @cache_property def z_relations(self) -> list: """ - Return all distinct set classes with the same interval vector (Allan Forte: "Z-related"). + Return all distinct set classes with the same interval vector (Allen Forte: "Z-related"). For example, Forte 4-Z15 {0,1,4,6} and Forte 4-Z29 {0,1,3,7} both have iv⟨1,1,1,1,1,1⟩ but are not inversions, complements, or transpositions (rotations) of each other. """