Add first pass at new API docs for V2

Signed-off-by: Patrick Avery <[email protected]>

.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+sphinx:
+  configuration: docs/api/source/conf.py
+
+python:
+  install:
+    - requirements: docs/api/requirements.txt
+    - method: pip
+      path: .

docs/api/README.md

@@ -1,38 +1,15 @@
-# API Documentation
+To build the docs, first install the requirements in the `docs/`
+directory via:
 
-These are docs autogenerated from the module itself.
-
-# Building API Documentation
-
-You must build the docs with a python interpreter that has sphinx and trame dependencies. We recommend using a virtual environment and the requirements.txt dependencies provided in this directory.
 ```
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r docs/api/requirements.txt
-sphinx-build docs/api/source/ docs/api/dist/
-```
-
-# Adding new module
-1. Copy this template into a new file in this directory, changeing `myCoolModule` to your module name.
+pip install -r requirements.txt
 ```
-trame.html.myCoolModule
-======================
-.. automodule:: trame.html.myCoolModule
-   :members:
-   :undoc-members:
-   :show-inheritance:
-```
-
-2. (Optional) Hide parts of the module with `:exclude-members:`. You can see an example of this in `trame.html.vtk.rst`.
-
-3. (Optional) Show imported members with `:imported-members:`. You can see an example of this in `trame.html.vtk.rst`.
 
-4. Preview your docs by building and opening index.html
-
-# Expected warnings:
+Then, run the bash script in the `docs/` directory:
 
-We expose `vtk.common.*` through both html.paraview and html.vtk, which confuses the index for sphinx. We get many warnings looking like this.
 ```
-WARNING: duplicate object description of trame.html.vtk.common.*, other instance in trame.html.paraview, use :noindex: for one of them
+./local_build.sh
 ```
 
+The sphinx html documentation will be built and placed inside the
+`dist` directory.

docs/api/local_build.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Clean up the current documentation
+rm -rf dist
+mkdir dist
+
+# Build and open
+sphinx-build source dist
+google-chrome ./dist/index.html

docs/api/requirements.txt

@@ -1,61 +1,3 @@
-aiohttp==3.7.4.post0
-alabaster==0.7.12
-astunparse==1.6.3
-async-timeout==3.0.1
-attrs==21.2.0
-Babel==2.9.1
-certifi==2021.10.8
-chardet==4.0.0
-charset-normalizer==2.0.7
-click==8.0.3
-docutils==0.17.1
-ghp-import==2.0.2
-html2text==2020.1.16
-idna==3.3
-imagesize==1.2.0
-importlib-metadata==4.8.1
-Jinja2==3.0.2
-Markdown==3.3.4
-markdown-it-py==1.1.0
-MarkupSafe==2.0.1
-mdit-py-plugins==0.2.8
-mergedeep==1.3.4
-mkdocs==1.2.3
-mkdocs-autorefs==0.3.0
-mkdocstrings==0.16.2
-multidict==5.2.0
-myst-parser==0.15.2
-packaging==21.2
-pydash==5.1.0
-Pygments==2.10.0
-pymdown-extensions==9.0
-pyparsing==2.4.7
-python-dateutil==2.8.2
-pytkdocs==0.12.0
-pytz==2021.3
-pywebvue==2.1.10
-PyYAML==6.0
-pyyaml-env-tag==0.1
-requests==2.26.0
-simput==2.0.0
-six==1.16.0
-snowballstemmer==2.1.0
-Sphinx==4.2.0
-sphinx-markdown-builder==0.5.4
-sphinx-rtd-theme==1.0.0
-sphinxcontrib-applehelp==1.0.2
-sphinxcontrib-devhelp==1.0.2
-sphinxcontrib-htmlhelp==2.0.0
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.3
-sphinxcontrib-serializinghtml==1.1.5
-typing-extensions==3.10.0.2
-unify==0.5
-untokenize==0.1.1
-urllib3==1.26.7
-vtk>=9.0.1
-watchdog==2.1.6
-wslink==1.1.0
-yapf==0.31.0
-yarl==1.7.0
-zipp==3.6.0
+pygments
+sphinx
+sphinx-rtd-theme

docs/api/source/.gitignore

@@ -0,0 +1,2 @@
+# These are auto-generated
+trame.*

docs/api/source/apidoc_templates/module.rst_t

@@ -0,0 +1,10 @@
+{%- if show_headings %}
+{% set basename_split = basename.split(".") %}
+{{- basename_split | last | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
+

docs/api/source/apidoc_templates/package.rst_t

@@ -0,0 +1,53 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, "namespace"] | join(" ") | e | heading }}
+{% else %}
+{% set pkgname_split = pkgname.split(".") %}
+{{- pkgname_split | last | e | heading }}
+{% endif %}
+
+{%- if is_namespace %}
+.. py:module:: {{ pkgname }}
+{% endif %}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
+
+{%- if not modulefirst and not is_namespace %}
+Module contents
+---------------
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}

docs/api/source/apidoc_templates/toc.rst_t

@@ -0,0 +1,8 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+

docs/api/source/conf.py

@@ -1,81 +1,86 @@
 # Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
+from pathlib import Path
 
-# 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
-
-this_dir = os.path.dirname(os.path.realpath(__file__))
-sys.path.insert(0, os.path.join(this_dir, "/../../../trame"))
+from sphinx.ext import apidoc
 
+import trame
 
 # -- Project information -----------------------------------------------------
 
-project = "trame"
-copyright = "2021, Kitware Inc."
-author = "Kitware Inc."
-
+project = "Trame"
+copyright = "2022, Kitware"
+author = "Kitware"
 
 # -- General configuration ---------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-import sphinx_rtd_theme
-
 extensions = [
-    "sphinx_rtd_theme",
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
     "sphinx.ext.autodoc",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.todo",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
 ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
 
-# 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 = "en"
+templates_path = ["_templates"]
 
 # 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"]
 
+# -- Options for autodoc -----------------------------------------------------
+autodoc_member_order = "bysource"
+autodoc_mock_imports = [
+    "IPython",
+]
 
 # -- 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 = "alabaster"
 html_theme = "sphinx_rtd_theme"
 
-# 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"]
 
+# -- Hooks for sphinx events -------------------------------------------------
 
-# -- Extension configuration -------------------------------------------------
+def run_apidoc(_):
 
-# -- Options for todo extension ----------------------------------------------
+    # Override the apidoc options with what we want
+    apidoc.OPTIONS.clear()
+    apidoc.OPTIONS.extend([
+        "members",
+        "imported-members",
+    ])
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+    ignore_paths = []
 
+    cur_path = str(Path(__file__).parent)
+    templates_path = str(Path(cur_path) / "apidoc_templates")
+    module_path = str(Path(trame.__file__).parent)
 
-autodoc_mock_imports = ["vtkmodules.vtkWebCore", "vtkmodules.web", "pywebvue.modules"]
+    argv = [
+        "-f",
+        "-T",
+        "-e",
+        "-M",
+        "-o", cur_path,
+        "-t", templates_path,
+        module_path,
+    ] + ignore_paths
 
-autodoc_member_order = "bysource"
+    apidoc.main(argv)
+
+
+def maybe_skip_member(app, what, name, obj, skip, options):
+    # Implement logic here for whether to skip certain members
+    return skip
+
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)
+    app.connect('autodoc-skip-member', maybe_skip_member)

docs/api/source/index.rst

@@ -1,19 +1,25 @@
-.. trame documentation master file, created by
-   sphinx-quickstart on Wed Nov  3 09:45:49 2021.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to trame's documentation!
+Welcome to Trame's documentation!
 =================================
 
-This is the auto-generated API documentation for trame, but the project website is `here <https://kitware.github.io/trame/>`_ with additional guides.
-All classes are listed in the :ref:`genindex`.
+.. note::
+
+   Trame v2 is under active development.
+
+.. toctree::
+   :hidden:
+   :caption: Trame API
+
+   trame.app.rst
+   trame.widgets.rst
+   trame.ui.rst
+   trame.assets.rst
+   trame.env.rst
 
 .. toctree::
-   :maxdepth: 1
+   :hidden:
+   :caption: Tools
 
-   trame
-   trame.html
-   trame.layouts
+   tools.www.rst
+   tools.docker.rst
 
 .. include:: ../../../README.rst

docs/api/source/tools.docker.rst

@@ -0,0 +1,2 @@
+Docker
+======

docs/api/source/tools.www.rst

@@ -0,0 +1,2 @@
+WWW
+===