From bcf9be9be60148c69d31582859d13d55abfe0d74 Mon Sep 17 00:00:00 2001 From: Mike Boyle Date: Tue, 1 Oct 2024 12:39:26 -0400 Subject: [PATCH] Avoid mktheapidocs --- .github/scripts/update_versions.py | 9 -- docs/Makefile | 19 --- docs/api.rst | 12 -- docs/calculus.md | 1 + docs/conf.py | 241 ----------------------------- docs/index.rst | 23 --- docs/javascript/mathjax.js | 15 ++ docs/means.md | 1 + docs/numpy.md | 66 ++++++++ docs/quaternion.md | 30 ++++ docs/style.css | 4 + docs/time_series.md | 1 + mkdocs.yml | 49 ++++-- pyproject.toml | 10 +- 14 files changed, 161 insertions(+), 320 deletions(-) delete mode 100644 docs/Makefile delete mode 100644 docs/api.rst create mode 100644 docs/calculus.md delete mode 100644 docs/conf.py delete mode 100644 docs/index.rst create mode 100644 docs/javascript/mathjax.js create mode 100644 docs/means.md create mode 100644 docs/numpy.md create mode 100644 docs/quaternion.md create mode 100644 docs/style.css create mode 100644 docs/time_series.md diff --git a/.github/scripts/update_versions.py b/.github/scripts/update_versions.py index 77530e7..e816c25 100644 --- a/.github/scripts/update_versions.py +++ b/.github/scripts/update_versions.py @@ -15,15 +15,6 @@ def update(version): for line in f: print(pattern.sub(replacement, line), end="") - files = ("docs/conf.py") - pattern = re.compile('^release *= *".*?"') - short_pattern = re.compile('^version *= *".*?"') - replacement = r'release = "' + version + '"' - short_replacement = r'version = "' + short_version + '"' - with fileinput.input(files=files, inplace=True) as f: - for line in f: - print(short_pattern.sub(short_replacement, pattern.sub(replacement, line)), end="") - version = os.environ["new_version"] diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 298ea9e..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SOURCEDIR = . -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) \ No newline at end of file diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 7ff689f..0000000 --- a/docs/api.rst +++ /dev/null @@ -1,12 +0,0 @@ -*********** -Package API -*********** - -.. autosummary:: - :toctree: _autosummary - - quaternion - quaternion.calculus - quaternion.means - quaternion.numpy_quaternion - quaternion.quaternion_time_series diff --git a/docs/calculus.md b/docs/calculus.md new file mode 100644 index 0000000..1f67ca5 --- /dev/null +++ b/docs/calculus.md @@ -0,0 +1 @@ +# ::: quaternion.calculus diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index f7bf139..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,241 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys - -import sphinx - -from recommonmark.parser import CommonMarkParser - - -# -- Project information ----------------------------------------------------- - -project = 'quaternion' -copyright = '2024, Michael Boyle' -author = 'Michael Boyle' - -# The short X.Y version -version = "2021.0a0" -# The full version, including alpha/beta/rc tags -release = "2021.0.0-alpha.0" - - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'numpydoc', - 'sphinx.ext.doctest', - 'sphinx.ext.todo', - 'sphinx.ext.mathjax', - 'sphinx.ext.ifconfig', - 'sphinx.ext.viewcode', - 'recommonmark', -] - -autosummary_generate = True - -autodoc_docstring_signature = True -if sphinx.version_info < (1, 8): - autodoc_default_flags = ['members', 'undoc-members'] -else: - autodoc_default_options = {'members': None, - 'undoc-members': None, - 'special-members': '__call__'} - -# -- Try to auto-generate numba-decorated signatures ----------------- - -import numba -import inspect - -def process_numba_docstring(app, what, name, obj, options, signature, return_annotation): - if type(obj) is not numba.core.registry.CPUDispatcher: - return (signature, return_annotation) - else: - original = obj.py_func - orig_sig = inspect.signature(original) - - if (orig_sig.return_annotation) is inspect._empty: - ret_ann = None - else: - ret_ann = orig_sig.return_annotation.__name__ - - return (str(orig_sig), ret_ann) - -def setup(app): - app.connect('autodoc-process-signature', process_numba_docstring) - -# -------------------------------------------------------------------- - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -if sphinx.version_info < (1, 8): - source_parsers = { - '.md': CommonMarkParser, - } - source_suffix = ['.rst', '.md'] -else: - source_suffix = { - '.rst': 'restructuredtext', - '.txt': 'markdown', - '.md': 'markdown', - } - -# The master toctree document. -master_doc = 'index' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# 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 - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = None - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# 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'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - - -# -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = 'quaterniondoc' - - -# -- Options for LaTeX output ------------------------------------------------ - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'quaternion.tex', 'quaternion Documentation', - 'Michael Boyle', 'manual'), -] - - -# -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'quaternion', 'quaternion Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'quaternion', 'quaternion Documentation', - author, 'quaternion', 'One line description of project.', - 'Miscellaneous'), -] - - -# -- Options for Epub output ------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# -# epub_identifier = '' - -# A unique identification for the text. -# -# epub_uid = '' - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - - -# -- Extension configuration ------------------------------------------------- - -# -- Options for intersphinx extension --------------------------------------- - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} - -# -- Options for todo extension ---------------------------------------------- - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 7c775c0..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. quaternion documentation master file, created by - sphinx-quickstart on Wed Jul 24 18:28:01 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to quaternion's documentation! -====================================== - -For a quick start, take a look at the `usage section `_ of the README. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - README.md - api - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/javascript/mathjax.js b/docs/javascript/mathjax.js new file mode 100644 index 0000000..c32d847 --- /dev/null +++ b/docs/javascript/mathjax.js @@ -0,0 +1,15 @@ +window.MathJax = { + tex: { + inlineMath: [["$", "$"], ["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + } +}; + +document$.subscribe(() => { + MathJax.startup.output.clearCache() + MathJax.typesetClear() + MathJax.texReset() + MathJax.typesetPromise() +}) diff --git a/docs/means.md b/docs/means.md new file mode 100644 index 0000000..74402ad --- /dev/null +++ b/docs/means.md @@ -0,0 +1 @@ +# ::: quaternion.means diff --git a/docs/numpy.md b/docs/numpy.md new file mode 100644 index 0000000..e072430 --- /dev/null +++ b/docs/numpy.md @@ -0,0 +1,66 @@ +# Numpy + +The most important part of this package's API is actually numpy's API, +because the `quaternion` type is added as a possible dtype for numpy +arrays. This means that everything you can do with numpy arrays will +also apply to quaternion arrays. + +It can be helpful to think of quaternions as generalized complex +numbers; all the operations that you can do with complex numbers are +also available for quaternions. This includes all the usual +arithmetic operations (addition, subtraction, multiplication, +division, and exponentiation), as well as exponential and logarithmic +functions. + +Here, we will single out a few of the very most important numpy +functions that are particularly useful for quaternions. + +## `numpy.exp(q)` + +This returns the exponential function applied to each quaternion in +the array. This is the quaternion analog of the exponential function +for complex numbers. The interpretation is that if `q` is the +axis-angle representation of a rotation, then `numpy.exp(q)` is the +quaternion representation of the same rotation. + +```python +import numpy as np +import quaternion +q = quaternion.from_float_array([[0, np.pi/4, 0, 0], [0, 0, np.pi/2, 0]]) +R = np.exp(q) +print(R) +``` +Here, `q` contains two quaternions, which are the axis-angle +representations of a $\pi/4$ (45°) rotation about the x-axis and a +$\pi/2$ (90°) rotation about the y-axis. The output is +```python +[quaternion(0.707107, 0.707107, 0, 0) + quaternion(0, 0, 1, 0)] +``` +which represent the same things as unit quaternions. + + +## `numpy.log(R)` + +The `log` function is (almost) the inverse of the `exp` function. In +particular, we can go backwards from the `R` defined above to get back +to `q`. If we evaluate + +```python +print(np.log(R)) +``` + +we see that the result is precisely the same as `q`. + + +## `ndarray.conjugate()` + +Just as with complex numbers and the complex conjugate, the quaternion +conjugate is extremely important. + +```python +R.conjugate() +R.conj() +``` + + diff --git a/docs/quaternion.md b/docs/quaternion.md new file mode 100644 index 0000000..bbc78b9 --- /dev/null +++ b/docs/quaternion.md @@ -0,0 +1,30 @@ +# Top-level functions + +These are functions that are available directly in the top level of +the `quaternion` module. + +::: quaternion + options: + members: + #- quaternion + - rotate_vectors + - as_quat_array + - from_float_array + - as_float_array + - from_vector_part + - as_vector_part + - from_rotation_matrix + - as_rotation_matrix + - from_rotation_vector + - as_rotation_vector + - from_euler_angles + - as_euler_angles + - from_spherical_coords + - as_spherical_coords + - as_spinor_array + - isclose + - allclose + #- rotor_intrinsic_distance + #- rotor_chordal_distance + #- rotation_intrinsic_distance + #- rotation_chordal_distance diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..bb148dc --- /dev/null +++ b/docs/style.css @@ -0,0 +1,4 @@ +/* Add space between function docstrings */ +div.doc.doc-object.doc-function:not(:first-of-type) { + margin-top: 60px; +} diff --git a/docs/time_series.md b/docs/time_series.md new file mode 100644 index 0000000..46ff2ec --- /dev/null +++ b/docs/time_series.md @@ -0,0 +1 @@ +# ::: quaternion.quaternion_time_series diff --git a/mkdocs.yml b/mkdocs.yml index dfcc102..ca76e2e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,19 +3,46 @@ site_name: quaternion repo_url: "https://github.com/moble/quaternion" plugins: - - search - - mktheapidocs: - modules: - quaternion: - section: "Package API:" - source_repo: "https://github.com/moble/quaternion/blob/main/src" +- search +- mkdocstrings: + enable_inventory: true + default_handler: python + handlers: + python: + options: + show_symbol_type_heading: true + docstring_style: numpy + +markdown_extensions: + - footnotes + - toc: + permalink: true theme: - name: 'readthedocs' + name: "material" + #name: "mkdocs" + #name: "readthedocs" + features: + - content.code.copy + +extra_css: + - style.css extra_javascript: - - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js + - javascript/mathjax.js + - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js -markdown_extensions: - - pymdownx.arithmatex: - generic: true +nav: + - "Home": README.md + - "API": + - "Numpy": numpy.md + - "Quaternion": quaternion.md + - "Time series": time_series.md + - "Means and alignment": means.md + - "Calculus": calculus.md + +# [ReadTheDocs](https://readthedocs.org/) is the service that hosts the documentation, which calls +# [MkDocs](https://www.mkdocs.org/), which is the generic backbone that calls +# [mkdocstrings](https://mkdocstrings.github.io/) to generate the API documentation, which uses +# [mkdocstrings-python](https://mkdocstrings.github.io/python/) to handle python, which uses +# [griffe](https://mkdocstrings.github.io/griffe/) to handle the actual parsing of the docstrings. diff --git a/pyproject.toml b/pyproject.toml index 558907c..3675a46 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -29,9 +29,9 @@ Documentation = "https://quaternion.readthedocs.io/en/latest" [project.optional-dependencies] docs = [ - "mkdocs", - "mktheapidocs", - "pymdown-extensions", + "mkdocs-material", + "mkdocstrings-python", + "pymdown-extensions" ] [build-system] @@ -50,8 +50,8 @@ test = "pytest {args:tests}" [tool.hatch.envs.docs] dependencies = [ - "mkdocs", - "mktheapidocs", + "mkdocs-material", + "mkdocstrings-python", "pymdown-extensions" ] [tool.hatch.envs.docs.scripts]