Render python native docs alongside API docs

.readthedocs.yml

@@ -15,6 +15,20 @@ build:
   os: "ubuntu-20.04"
   tools:
     python: "mambaforge-4.10"
+  # jobs:
+  #   pre_install:
+  #     - LATEST_TAG=$(git describe --tags --abbrev=0) ; echo Downloading $LATEST_TAG ;
+  #      wget https://github.com/tudat-team/tudatpy/archive/refs/tags/$LATEST_TAG.zip; unzip $LATEST_TAG.zip; rm -rf docs/; LT=$(echo $LATEST_TAG | cut -c 2-); mv tudatpy-$LT/docs/ .
+      # The pre-install step enables building the docs on the latest tag
+      # instead of the latest commit. Since Read the Docs uses the latest
+      # tudatpy dev conda package to find the binaries (see docs/source/conf.
+      # py) and extract docs form them, it must use the corresponding source
+      # code to build the docs to avoid any inconsistencies. The pre-install
+      # step overrides the default behavior of Read the Docs to build the docs
+      # on the latest commit. The pre-install step replaces the docs/
+      # directory with the docs/ directory of the latest tag.
 
 conda:
   environment: docs/environment_readthedocs.yaml
+
+

docs/source/conf.py

@@ -16,61 +16,32 @@
 # 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
 
-sys.path.insert(0, os.path.abspath('.'))
+# sys.path.insert(0, os.path.abspath("."))
 
-# -- Multidoc configuration --------------------------------------------------
-# Alternative preparation required if building docs on readthedocs.
+# When the docs are being built on ReadTheDocs, the binaries are in the tudatpy conda package installed in site-packages directory.
 if bool(os.getenv("READTHEDOCS")) is True:
-    from document import *
-    from urllib.request import urlopen
-    import json
-    from datetime import datetime
-
-    multidoc_git_url = 'https://github.com/tudat-team/tudat-multidoc.git'
-    multidoc_git_rev = None # If left at None, latest version is used
-    # multidoc_git_rev = '96d2748ea2a203c797552f56155f1703524f53f6'
-
-    # Return the latest timestamp of the tudapty conda package for a given label (dev/main)
-    def get_latest_conda_package(label):
-        # Get json data from conda repo
-        response = urlopen('https://conda.anaconda.org/tudat-team/label/%s/linux-64/repodata.json' % label)
-        data_json = json.loads(response.read())
-        latest_package = 0
-        # Go trough tudatpy packages and find the latest version
-        for package_name, package_info in data_json['packages'].items():
-            if package_name.startswith('tudatpy'):
-                package_timestamp = package_info['timestamp']
-                latest_package = max(latest_package, package_timestamp)
-        return latest_package
-
-    latest_main_package = get_latest_conda_package('main')
-    print('Latest main package time:', datetime.fromtimestamp(latest_main_package/1e3))
-    latest_dev_package = get_latest_conda_package('dev')
-    print('Latest dev package time:', datetime.fromtimestamp(latest_dev_package/1e3))
-
-    # Install the dev version of the tudatpy package if it was the latest to be published
-    install_dev_tudatpy = latest_dev_package >= latest_main_package
-    print("Tudatpy dev version will%s be installed." % ("" if install_dev_tudatpy else " not"))
-    if install_dev_tudatpy:
-        os.system('conda install -c tudat-team/label/dev tudatpy -y')
-
-
-    # clone repository
-    docstring_path = get_docstrings(multidoc_git_url, multidoc_git_rev)
-
-    # parse api declaration
-    api_declaration = parse_api_declaration(docstring_path, py=True)
-
-    # source path
-    source_path = generate_documentation(api_declaration, '.')
+    import importlib.util
+
+    # Find the path where the package is installed
+    tudatpy_path = importlib.util.find_spec("tudatpy").origin
+
+    # Extract the directory up to site-packages
+    site_packages_path = os.path.dirname(os.path.dirname(tudatpy_path))
+
+    # Print the path
+    print(f"site-packages path is: {site_packages_path}")
+
+    # Insert the site-packages path to sys.path
+    sys.path.insert(0, os.path.abspath(site_packages_path))
+    print("sys.path:", sys.path)
 
 else:
     # when building locally, use the binaries generated with tudat-bundle
-    sys.path.insert(0, os.path.abspath('../../../build/tudatpy'))
+    sys.path.insert(0, os.path.abspath("../../../build/tudatpy"))
 
 # -- General configuration ------------------------------------------------
 
@@ -81,25 +52,26 @@ def get_latest_conda_package(label):
 # 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.todo',
-              'sphinx.ext.coverage',
-              'sphinx.ext.mathjax',
-              'sphinx.ext.ifconfig',
-              'sphinx.ext.viewcode',
-              'sphinx.ext.githubpages',
-              'sphinx.ext.napoleon',
-              'sphinx.ext.autosectionlabel',
-              'sphinx_copybutton'
-              # 'breathe',
-              # 'exhale'
-              ]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosectionlabel",
+    "sphinx_copybutton",
+    # 'breathe',
+    # 'exhale'
+]
 autosummary_generate = True  # Turn on sphinx.ext.autosummary
 
 add_module_names = False
-autodoc_member_order = 'groupwise'
+autodoc_member_order = "groupwise"
 
 # napoleon_type_aliases = {
 #     "Dict": ":class:`~typing.Dict`",
@@ -120,30 +92,30 @@ def get_latest_conda_package(label):
 
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = 'TudatPy API'
-copyright = '2021, Tudat Team'
-author = 'Tudat Team'
+project = "TudatPy API"
+copyright = "2021, Tudat Team"
+author = "Tudat Team"
 
 # 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 = ''
+version = ""
 # The full version, including alpha/beta/rc tags.
-release = ''
+release = ""
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -158,7 +130,7 @@ def get_latest_conda_package(label):
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
@@ -169,7 +141,7 @@ def get_latest_conda_package(label):
 # a list of builtin themes.
 #
 # html_theme = 'sphinx_rtd_theme'
-html_theme = 'furo'
+html_theme = "furo"
 html_theme_options = {
     "navigation_with_keys": True,
     "announcement": "<em>These docs are a work-in-progress!</em>",
@@ -184,9 +156,9 @@ def get_latest_conda_package(label):
 # 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']
+html_static_path = ["_static"]
 html_css_files = [
-    'style.css',
+    "style.css",
 ]
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -203,24 +175,21 @@ def get_latest_conda_package(label):
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'TudatPy API'
-html_title = 'TudatPy API Reference'
+htmlhelp_basename = "TudatPy API"
+html_title = "TudatPy API Reference"
 
 # -- 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',
@@ -230,38 +199,41 @@ def get_latest_conda_package(label):
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'tudat-api.tex', 'TudatPy API',
-     'John', 'manual'),
+    (master_doc, "tudat-api.tex", "TudatPy API", "John", "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, 'tudat-api', 'TudatPy API',
-     [author], 1)
-]
+man_pages = [(master_doc, "tudat-api", "TudatPy API", [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, 'tudat-api', 'TudatPy API',
-     author, 'tudat-api', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "tudat-api",
+        "TudatPy API",
+        author,
+        "tudat-api",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
 
 # intersphinx_mapping = {'https://docs.python.org/': None}
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
-    'pagmo': ('https://esa.github.io/pagmo2/', None),
-    'numpy': ('http://docs.scipy.org/doc/numpy/', None),
-    'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
-    'matplotlib': ('https://matplotlib.org/stable/api/', None)}
+    "python": ("https://docs.python.org/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+    "pagmo": ("https://esa.github.io/pagmo2/", None),
+    "numpy": ("http://docs.scipy.org/doc/numpy/", None),
+    "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None),
+    "matplotlib": ("https://matplotlib.org/stable/api/", None),
+}

docs/source/ephemeris.rst

@@ -5,9 +5,9 @@ ephemeris models of celestial bodies in an environment. Below a short
 overview of aspects of some of the ephemeris models in order to aid in
 properly selecting an choosing a model.
 
-**Spice-based models** For many typical applications, natural body ephemerides 
-will be calculated from `Spice kernels <https://docs.tudat.space/en/latest/_src_user_guide/state_propagation/environment_setup/default_env_models.html#spice-in-tudat>`_. 
-In some cases, a user may find that the default Spice kernels are insufficient 
+**Spice-based models** For many typical applications, natural body ephemerides
+will be calculated from `Spice kernels <https://docs.tudat.space/en/latest/_src_user_guide/state_propagation/environment_setup/default_env_models.html#spice-in-tudat>`_.
+In some cases, a user may find that the default Spice kernels are insufficient
 for their purposes, due to one of two reasons:
 
 * The body for which the state is required *is* in the ephemeris Spice kernel, but the time at which the state is needed lies outside of the bounds for which the Spice kernel has data
@@ -36,7 +36,7 @@ inertial Cartesian state elements produced by the ephemeris.
 
 where the ``epoch`` input is (as always in Tudat) the time in seconds since J2000. The ``earth_state_at_epoch`` is always in a frame with inertial orientation. The specific orientation and origin can be access from the :attr:`~tudatpy.numerical_simulation.environment.Ephemeris.frame_orientation` and :attr:`~tudatpy.numerical_simulation.environment.Ephemeris.frame_origin` attributes.
 
-
+* jpl_horizons (:func:`~tudatpy.numerical_simulation.environment_setup.ephemeris.horizons_wrapper.jpl_horizons`)
 
 
 
@@ -77,6 +77,7 @@ Functions
 
    tabulated_from_existing
 
+   horizons_wrapper.jpl_horizons
 
 
 .. autofunction:: tudatpy.numerical_simulation.environment_setup.ephemeris.direct_spice
@@ -103,7 +104,7 @@ Functions
 
 .. autofunction:: tudatpy.numerical_simulation.environment_setup.ephemeris.tabulated_from_existing
 
-
+.. autofunction:: tudatpy.numerical_simulation.environment_setup.ephemeris.horizons_wrapper.jpl_horizons
 
 
 

docs/source/gravity_field.rst

@@ -15,7 +15,7 @@ Rigid body properties will always be created automatically when a body is endowe
 * Spherical harmonic gravity field: mass computed from gravitational parameter, center of mass computed from degree 1 gravity field coefficients, inertia tensor as described in :func:`~tudatpy.numerical_simulation.environment_setup.gravity_field.spherical_harmonic`
 * Polyhedron gravity field: mass computed from gravitational parameter, center of mass and inertia tensor computed from homogeneous mas distribution inside body
 
-
+* sbdb_wrapper (:func:`~tudatpy.numerical_simulation.environment_setup.gravity_field.sbdb_wrapper.central_sbdb`)
 
 
 
@@ -59,6 +59,9 @@ Functions
 
    polyhedron_from_density
 
+   sbdb_wrapper.central_sbdb
+
+   sbdb_wrapper.central_sbdb_density
 
 
 .. autofunction:: tudatpy.numerical_simulation.environment_setup.gravity_field.central
@@ -79,7 +82,9 @@ Functions
 
 .. autofunction:: tudatpy.numerical_simulation.environment_setup.gravity_field.polyhedron_from_density
 
+.. autofunction:: tudatpy.numerical_simulation.environment_setup.gravity_field.sbdb_wrapper.central_sbdb
 
+.. autofunction:: tudatpy.numerical_simulation.environment_setup.gravity_field.sbdb_wrapper.central_sbdb_density
 
 
 Enumerations

docs/source/porkchop.rst

@@ -0,0 +1,18 @@
+``porkchop``
+======================
+
+
+Functions
+---------
+.. currentmodule:: tudatpy.trajectory_design.porkchop.porkchop
+
+.. autosummary::
+
+   porkchop
+
+
+
+
+.. autofunction:: tudatpy.trajectory_design.porkchop.porkchop.porkchop
+
+