docs: add documentation (#132)

* docs: add documentation

* feat: missed a spot

.gitignore

@@ -40,6 +40,12 @@ coverage/
 
 docs/html/
 docs/latex/
+docs/xml/
+docs/_autosummary
+docs/_build
+docs/_notebooks
+docs/cpp_rst
+
 
 ## Misc.
 

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
 

README.md

@@ -29,7 +29,7 @@ Want to get started? This is the simplest and quickest way:
 The following command will start an [iPython](https://ipython.org/) shell within a container where the OSTk components are already installed:
 
 ```bash
-docker run -it openspacecollective/open-space-toolkit-mathematics-python
+docker run -it openspacecollective/open-space-toolkit-mathematics-development python3.11 -m IPython
 ```
 
 Once the shell is up and running, playing with it is easy:
@@ -260,7 +260,7 @@ cmake ..
 make
 ```
 
-*Tip: `helpers/build.sh` simplifies building from within the development environment.*
+*Tip: `ostk-build` simplifies building from within the development environment.*
 
 ### Test
 
@@ -276,13 +276,13 @@ Or to run them manually:
 ./bin/open-space-toolkit-mathematics.test
 ```
 
-*Tip: `helpers/test.sh` simplifies running tests from within the development environment.*
+*Tip: `ostk-test` simplifies running tests from within the development environment.*
 
 ## Dependencies
 
 | Name                   | Version  | License                | Link                                                                                                                         |
 | ---------------------- | -------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| Pybind11               | `2.10.1` | BSD-3-Clause           | [github.com/pybind/pybind11](https://github.com/pybind/pybind11)                                                             |
+| Pybind11               | `2.12.0` | BSD-3-Clause           | [github.com/pybind/pybind11](https://github.com/pybind/pybind11)                                                             |
 | {fmt}                  | `5.2.0`  | BSD-2-Clause           | [github.com/fmtlib/fmt](https://github.com/fmtlib/fmt)                                                                       |
 | Eigen                  | `3.3.7`  | MPL2                   | [eigen.tuxfamily.org](http://eigen.tuxfamily.org/index.php)                                                                  |
 | Geometric Tools Engine | `3.28`   | Boost Software License | [geometrictools.com](https://www.geometrictools.com)                                                                         |

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
+# "<project> v<release> 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

docs/cpp.rst

@@ -0,0 +1,8 @@
+C++ API Documentation
+=====================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   cpp_rst/class/*

docs/doxygen/Doxyfile.in

@@ -1817,7 +1817,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

docs/index.html

@@ -2,7 +2,7 @@
 <html>
 
     <head>
-        <meta http-equiv="refresh" content="0; url=https://open-space-collective.github.io/open-space-toolkit-mathematics/html/index.html" />
+        <meta http-equiv="refresh" content="0; url=https://open-space-collective.github.io/open-space-toolkit-mathematics/_build/html/index.html" />
     </head>
 
     <body>

docs/index.md

@@ -0,0 +1,12 @@
+```{include} ../README.md
+:relative-docs: ./
+:relative-images:
+```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+cpp
+python
+```

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

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

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 %}