Merge pull request #195 from ZacZhangzhuo/sphinx-book

Sphinx book theme

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+* Doc building using `sphinx_compas2_theme `.
+* Fix the documentation: title lines, comments.
 * Fix a bug when camera is looking straight up or down.
 
 ### Removed

docs/conf.py

@@ -1,117 +1,79 @@
 # flake8: noqa
 # -*- coding: utf-8 -*-
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = "1.0"
-
-import sys
-import os
-import inspect
-import importlib
-
-import sphinx_compas_theme
-from sphinx.ext.napoleon.docstring import NumpyDocstring
-
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../src'))
+import sphinx_compas2_theme
+from sphinx.writers import html
+from sphinx.writers import html5
 
 # -- General configuration ------------------------------------------------
 
 project = "COMPAS View2"
-copyright = "Block Research Group - ETH Zurich"
+copyright = "COMPAS Association"
 author = "tom van mele"
-release = "0.10.1"
-version = ".".join(release.split(".")[0:2])
+organization = "compas-dev"
+package = "compas_view2"
 
 master_doc = "index"
-source_suffix = [".rst", ]
-templates_path = sphinx_compas_theme.get_autosummary_templates_path()
-exclude_patterns = []
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
+templates_path = sphinx_compas2_theme.get_autosummary_templates_path()
+exclude_patterns = sphinx_compas2_theme.default_exclude_patterns
+add_module_names = False
+language = "en"
 
-pygments_style   = "sphinx"
-show_authors     = True
-add_module_names = True
-language         = 'en'
+latest_version = sphinx_compas2_theme.get_latest_version()
 
+if latest_version == "Unreleased":
+    release = "Unreleased"
+    version = "latest"
+else:
+    release = latest_version
+    version = ".".join(release.split(".")[0:2])  # type: ignore
 
 # -- Extension configuration ------------------------------------------------
 
-extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.doctest",
-    "sphinx.ext.coverage",
-    "sphinx.ext.linkcode",
-    "sphinx.ext.extlinks",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.mathjax",
-    "sphinx.ext.napoleon",
-    "sphinx.ext.githubpages",
-    "matplotlib.sphinxext.plot_directive",
-]
+extensions = sphinx_compas2_theme.default_extensions
+
+# numpydoc options
+
+numpydoc_show_class_members = False
+numpydoc_class_members_toctree = False
+numpydoc_attributes_as_param_list = True
+
+# bibtex options
 
 # autodoc options
 
 autodoc_type_aliases = {}
-
-# this does not work properly yet
-autodoc_typehints = "none"
-autodoc_typehints_format = "short"
 autodoc_typehints_description_target = "documented"
-
+autodoc_mock_imports = sphinx_compas2_theme.default_mock_imports
 autodoc_default_options = {
     "undoc-members": True,
     "show-inheritance": True,
 }
-
-autodoc_member_order = "alphabetical"
+autodoc_member_order = "groupwise"
+autodoc_typehints = "description"
+autodoc_class_signature = "separated"
 
 autoclass_content = "class"
 
-def skip(app, what, name, obj, would_skip, options):
-    if name.startswith('_'):
-        return True
-    return would_skip
 
 def setup(app):
-    app.connect("autodoc-skip-member", skip)
+    app.connect("autodoc-skip-member", sphinx_compas2_theme.skip)
+
 
 # autosummary options
 
 autosummary_generate = True
+autosummary_mock_imports = sphinx_compas2_theme.default_mock_imports
 
-# napoleon options
-
-napoleon_google_docstring = False
-napoleon_numpy_docstring = True
-napoleon_include_init_with_doc = False
-napoleon_include_private_with_doc = False
-napoleon_include_special_with_doc = True
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
-napoleon_use_ivar = False
-napoleon_use_param = False
-napoleon_use_rtype = False
+# graph options
 
 # plot options
 
+plot_include_source = False
 plot_html_show_source_link = False
 plot_html_show_formats = False
-
-# docstring sections
-
-def parse_attributes_section(self, section):
-    return self._format_fields("Attributes", self._consume_fields())
-
-NumpyDocstring._parse_attributes_section = parse_attributes_section
-
-def patched_parse(self):
-    self._sections["attributes"] = self._parse_attributes_section
-    self._unpatched_parse()
-
-NumpyDocstring._unpatched_parse = NumpyDocstring._parse
-NumpyDocstring._parse = patched_parse
+plot_formats = ["png"]
 
 # intersphinx options
 
@@ -122,65 +84,75 @@ def patched_parse(self):
 
 # linkcode
 
-def linkcode_resolve(domain, info):
-    if domain != 'py':
-        return None
-    if not info['module']:
-        return None
-    if not info['fullname']:
-        return None
-
-    package = info['module'].split('.')[0]
-    if not package.startswith('compas_view2'):
-        return None
-
-    module = importlib.import_module(info['module'])
-    parts = info['fullname'].split('.')
-
-    if len(parts) == 1:
-        obj = getattr(module, info['fullname'])
-        filename = inspect.getmodule(obj).__name__.replace('.', '/')
-        lineno = inspect.getsourcelines(obj)[1]
-    elif len(parts) == 2:
-        obj_name, attr_name = parts
-        obj = getattr(module, obj_name)
-        attr = getattr(obj, attr_name)
-        if inspect.isfunction(attr):
-            filename = inspect.getmodule(obj).__name__.replace('.', '/')
-            lineno = inspect.getsourcelines(attr)[1]
-        else:
-            return None
-    else:
-        return None
-
-    return f"https://github.com/compas-dev/compas_view2/blob/master/src/{filename}.py#L{lineno}"
+linkcode_resolve = sphinx_compas2_theme.get_linkcode_resolve(organization, package)
 
 # extlinks
 
 extlinks = {}
 
+# from pytorch
+
+sphinx_compas2_theme.replace(html.HTMLTranslator)
+sphinx_compas2_theme.replace(html5.HTML5Translator)
+
 # -- Options for HTML output ----------------------------------------------
 
-html_theme = "compaspkg"
-html_theme_path = sphinx_compas_theme.get_html_theme_path()
+html_theme = "sidebaronly"
+html_title = project
+
+favicons = [
+    {
+        "rel": "icon",
+        "href": "compas.ico",  # relative to the static path
+    }
+]
 
 html_theme_options = {
-    "package_name"    : "compas_view2",
-    "package_title"   : project,
-    "package_version" : release,
-    "package_author"  : "compas-dev",
-    "package_docs"    : "https://compas.dev/compas_view2/",
-    "package_repo"    : "https://github.com/compas-dev/compas_view2",
-    "package_old_versions_txt": "https://compas.dev/compas_view2/doc_versions.txt"
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": f"https://github.com/{organization}/{package}",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
+        },
+        {
+            "name": "Discourse",
+            "url": "http://forum.compas-framework.org/",
+            "icon": "fa-brands fa-discourse",
+            "type": "fontawesome",
+        },
+        {
+            "name": "PyPI",
+            "url": f"https://pypi.org/project/{package}/",
+            "icon": "fa-brands fa-python",
+            "type": "fontawesome",
+        },
+    ],
+    "switcher": {
+        "json_url": f"https://raw.githubusercontent.com/{organization}/{package}/gh-pages/versions.json",
+        "version_match": version,
+    },
+    "logo": {
+        "image_light": "_static/compas_icon_white.png",  # relative to parent of conf.py
+        "image_dark": "_static/compas_icon_white.png",  # relative to parent of conf.py
+        "text": project,
+    },
+}
+
+html_context = {
+    "github_url": "https://github.com",
+    "github_user": organization,
+    "github_repo": package,
+    "github_version": "main",
+    "doc_path": "docs",
 }
 
-html_context = {}
-html_static_path = sphinx_compas_theme.get_html_static_path()
+html_static_path = sphinx_compas2_theme.get_html_static_path() + ["_static"]
+html_css_files = []
 html_extra_path = []
 html_last_updated_fmt = ""
 html_copy_source = False
-html_show_sourcelink = False
+html_show_sourcelink = True
 html_permalinks = False
 html_permalinks_icon = ""
-html_experimental_html5_writer = False
 html_compact_lists = True

docs/examples/control/example_custom_keys.rst

@@ -7,7 +7,7 @@ Custom Keys
     :nosignatures:
 
 Default Keys
-===========
+=============
 
 By default, the keys are like:
 
@@ -18,7 +18,7 @@ By default, the keys are like:
 
 
 Custom Keys
-===========
+=============
 
 You can customize the keys by modifying the ``keys`` parameter of the configuration.
 

docs/tutorials/tutorial_basics.rst

@@ -189,7 +189,7 @@ use the "on" decorator (:meth:`compas_view2.app.App.on`) on a callback function.
 
 
 Zoom, Pan, Rotate, and Select
-=================
+===============================
 
 After launching the viewer, the view can be transformed by zooming, panning, and rotating. Object selection is also possible.
 

docs/tutorials/tutorial_configuration.rst

@@ -25,7 +25,7 @@ Thinking of the ``options`` in :mod:`Rhino` , the ``preferences..`` in :mod:`Ble
 
 
 Customize Your Viewer
-===================
+=====================
 
 There are two ways to customize your viewer:
 
@@ -65,7 +65,7 @@ This is a quick way to customize your viewer. It is suitable for task-specific c
 
 
 Configuration Structure
-====================
+========================================
 The default configuration file can be downloaded here: :download:`Link <files/config_default.json>`,
 or can be printed by the following code:
 
@@ -78,7 +78,7 @@ or can be printed by the following code:
 It it the template for creating your own settings, keyboard preferences, etc.
 
 Supported Keys
-===============
+===================
 In the `controller -> keys`, you can add you preferred keys. Currently, :mod:`compas_view2` supports below keys:
 
 .. figure:: /_images/keyboard.png

docs/tutorials/tutorial_software_concepts.rst

@@ -25,21 +25,21 @@ to help you better the design concepts behind it.
 
 
 Software Architecture
-===========
+======================
 
 .. figure:: /_images/software_concept.png
      :figclass: figure
      :class: figure-img img-fluid
 
 
 UI Components
-===========
+===============
 .. figure:: /_images/UI.PNG
      :figclass: figure
      :class: figure-img img-fluid
 
 Configuration Structure
-===========
+===========================
 .. figure:: /_images/config_structure.png
      :figclass: figure
      :class: figure-img img-fluid

requirements-dev.txt

@@ -1,23 +1,13 @@
 attrs >=17.4
-black
+black ==22.12.0
 bump2version >=1.0.1
 check-manifest >=0.36
 compas_invocations
 doc8
 flake8
-graphviz
-importlib_metadata <5.0
 invoke >=0.14
-ipykernel
-ipython >=5.8
 isort
-jinja2 >= 3.0
-m2r2
-nbsphinx
-pydocstyle
-pytest
-sphinx == 7.1.2
-sphinx_compas_theme >=0.15.18
+sphinx_compas2_theme
 twine
 wheel
 -e .