From d9d1b1a4c48d212d806ca9cee3e888db3dc71355 Mon Sep 17 00:00:00 2001 From: Vishwa Shah Date: Tue, 18 Jun 2024 22:19:23 +0000 Subject: [PATCH] docs: add documentation --- .gitignore | 6 + Makefile | 6 +- docs/conf.py | 202 ++++++++++++++++++++++ docs/cpp.rst | 8 + docs/index.md | 12 ++ docs/python.rst | 19 ++ docs/requirements.txt | 10 ++ docs/templates/custom-class-template.rst | 34 ++++ docs/templates/custom-module-template.rst | 54 ++++++ 9 files changed, 349 insertions(+), 2 deletions(-) create mode 100644 docs/conf.py create mode 100644 docs/cpp.rst create mode 100644 docs/index.md create mode 100644 docs/python.rst create mode 100644 docs/requirements.txt create mode 100644 docs/templates/custom-class-template.rst create mode 100644 docs/templates/custom-module-template.rst diff --git a/.gitignore b/.gitignore index e735fea6..60ac582e 100755 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,12 @@ coverage/ docs/html/ docs/latex/ +docs/xml/ +docs/_autosummary +docs/_build +docs/_notebooks +docs/cpp_rst + ## Misc. diff --git a/Makefile b/Makefile index 0eeb8113..d12e5ad2 100644 --- a/Makefile +++ b/Makefile @@ -201,8 +201,10 @@ build-documentation-standalone: ## Build documentation (standalone) --volume="/app/build" \ --workdir=/app/build \ $(docker_development_image_repository):$(docker_image_version) \ - /bin/bash -c "cmake -DBUILD_UNIT_TESTS=OFF -DBUILD_PYTHON_BINDINGS=OFF -DBUILD_DOCUMENTATION=ON .. \ - && $(MAKE) docs" + /bin/bash -c "cmake -DBUILD_UNIT_TESTS=OFF -DBUILD_PYTHON_BINDINGS=ON -DBUILD_SHARED_LIBRARY=ON -DBUILD_DOCUMENTATION=ON .. \ + && ostk-build \ + && ostk-install-python \ + && ostk-build-docs" .PHONY: build-documentation-standalone diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..be6a86da --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,202 @@ +# +# python_example documentation build configuration file, created by +# sphinx-quickstart on Fri Feb 26 00:29:33 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +from ostk.mathematics import OpenSpaceToolkitMathematicsPy + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = "7.2" + +# 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.intersphinx", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx_math_dollar", + "sphinx_design", + "breathe", + "myst_nb", +] + + +# 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: +source_suffix = [".rst", ".md"] + +add_module_names = False + +# The master toctree document. +master_doc = "index" + +# General information about the project. +project = "Open Space Toolkit Mathematics" +copyright = "2024, Lucas Bremond" +author = "Lucas Bremond" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = OpenSpaceToolkitMathematicsPy.__version__ +# The full version, including alpha/beta/rc tags. +release = OpenSpaceToolkitMathematicsPy.__version__ + +# 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 = "english" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".ipynb_checkpoints"] + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + +python_maximum_signature_line_length = 88 + +# -- Autodoc configuration ------------------------------------------------ + +autosummary_generate = True # Turn on sphinx.ext.autosummary +# autodoc_typehints = "description" # Add type hints to __init__ params +autodoc_member_order = "bysource" # Order members by source order +html_show_sourcelink = ( + False # Remove 'view source code' from top of page (for html, not python) +) +autodoc_inherit_docstrings = True # If no docstring, inherit from base class +set_type_checking_flag = True # Enable 'expensive' imports for sphinx_autodoc_typehints +autoclass_content = "both" # Include both class docstring and __init__ + + +def skip_member(app, what, name, obj, skip, options): + if name in { + "OpenSpaceToolkitCorePy", + "OpenSpaceToolkitIOPy", + "OpenSpaceToolkitMathematicsPy", + "URL", + "ip", + "test", + }: + return True + + +def setup(app): + app.connect("autodoc-skip-member", skip_member) + + +# -- 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_material" + +# 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 = { + "base_url": "https://open-space-collective.github.io/open-space-toolkit-mathematics/html/index.html", + "repo_url": "https://github.com/open-space-collective/open-space-toolkit-mathematics", + "repo_name": "Open Space Toolkit Mathematics", + "html_minify": True, + "css_minify": True, + "nav_title": "Open Space Toolkit Mathematics", + "logo_icon": "🛰", + "color_primary": "indigo", + "color_accent": "blue", + "globaltoc_depth": 2, + "globaltoc_collapse": True, +} + +html_sidebars = {"**": ["globaltoc.html", "localtoc.html", "searchbox.html"]} + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = "Open Space Toolkit Mathematics" + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# 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"] + +# Output file base name for HTML help builder. +htmlhelp_basename = "ostk_mathematics_doc" + + +# -- 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, + "Open Space Toolkit Mathematics", + "Open Space Toolkit Mathematics Documentation", + [author], + 1, + ) +] + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "numpy": ("https://numpy.org/doc/stable/", None), + "ostk.core": ( + "https://open-space-collective.github.io/open-space-toolkit-core/_build/html/", + None, + ), +} + + +def autodoc_process_docstring(app, what, name, obj, options, lines): + for i in range(len(lines)): + lines[i] = lines[i].replace("np.", "numpy.") + # lines[i] = lines[i].replace("np.", "~numpy.") # For shorter links + lines[i] = lines[i].replace("F.", "torch.nn.functional.") + lines[i] = lines[i].replace("List[", "~typing.List[") + + +def setup(app): + app.connect("autodoc-process-docstring", autodoc_process_docstring) + + +# -- Breathe configuration ------------------------------------------------- +highlight_language = "c++" + +breathe_projects = {"C++ Sphinx Doxygen Breathe": "xml/"} +breathe_default_project = "C++ Sphinx Doxygen Breathe" +breathe_default_members = ("members", "undoc-members") + +# -- MyST NB configuration ------------------------------------------------- +nb_execution_cache_path = "notebooks" +nb_execution_timeout = 60 +myst_footnote_transition = False diff --git a/docs/cpp.rst b/docs/cpp.rst new file mode 100644 index 00000000..4d91e74e --- /dev/null +++ b/docs/cpp.rst @@ -0,0 +1,8 @@ +C++ API Documentation +===================== + +.. toctree:: + :glob: + :maxdepth: 1 + + cpp_rst/class/* \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..eb36e78b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,12 @@ +```{include} ../README.md +:relative-docs: ./ +:relative-images: +``` + +```{toctree} +:maxdepth: 1 +:hidden: + +cpp +python +``` \ No newline at end of file diff --git a/docs/python.rst b/docs/python.rst new file mode 100644 index 00000000..04f4356d --- /dev/null +++ b/docs/python.rst @@ -0,0 +1,19 @@ +Python API Documentation +======================== + +.. autosummary:: + :toctree: _autosummary + :template: custom-module-template.rst + :recursive: + + ostk.mathematics + ostk.mathematics.curve_fitting + ostk.mathematics.curve_fitting.interpolator + ostk.mathematics.geometry + ostk.mathematics.geometry.d2 + ostk.mathematics.geometry.d2.object + ostk.mathematics.geometry.d3 + ostk.mathematics.geometry.d3.object + ostk.mathematics.geometry.d3.transformation + ostk.mathematics.object + ostk.mathematics.solver \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..e075336a --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,10 @@ +# Apache License 2.0 + +sphinx~=7.2 +breathe~=4.35 +myst-parser~=2.0 +sphinx-math-dollar~=1.2 +sphinx-design~=0.5 +sphinx-material~=0.0 +kaleido~=0.2 +myst-nb~=1.0 diff --git a/docs/templates/custom-class-template.rst b/docs/templates/custom-class-template.rst new file mode 100644 index 00000000..d64b80d5 --- /dev/null +++ b/docs/templates/custom-class-template.rst @@ -0,0 +1,34 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :show-inheritance: + :inherited-members: + :special-members: __call__, __add__, __mul__ + + {% block methods %} + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + :nosignatures: + {% for item in methods %} + {%- if not item.startswith('_') %} + ~{{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} \ No newline at end of file diff --git a/docs/templates/custom-module-template.rst b/docs/templates/custom-module-template.rst new file mode 100644 index 00000000..2409e89a --- /dev/null +++ b/docs/templates/custom-module-template.rst @@ -0,0 +1,54 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + + {% block attributes %} + {% if attributes %} + .. rubric:: Module attributes + + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + :toctree: + :nosignatures: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :toctree: + :template: custom-class-template.rst + :nosignatures: + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + :toctree: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} \ No newline at end of file