diff --git a/CHANGELOG.md b/CHANGELOG.md index cacf4d445..95029090f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 * Change the str options in `view_port` into all lower case. * Change naming `view_mode` to `viewport_mode`, `view_port` to `viewport`. +* Doc building using `sphinx_compas2_theme `. +* Fix the documentation: title lines, comments. * Fix a bug when camera is looking straight up or down. ### Removed diff --git a/docs/conf.py b/docs/conf.py index ede583c06..d83a672fd 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/tutorials/tutorial_basics.rst b/docs/tutorials/tutorial_basics.rst index 670704476..4828e8093 100644 --- a/docs/tutorials/tutorial_basics.rst +++ b/docs/tutorials/tutorial_basics.rst @@ -191,6 +191,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. Below are list of default key-mouse combinations to perform these actions: diff --git a/requirements-dev.txt b/requirements-dev.txt index 227981033..164431b69 100644 --- a/requirements-dev.txt +++ b/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 >=3.4, <=7.1.2 -sphinx_compas_theme >=0.15.18 +sphinx_compas2_theme twine wheel -e . diff --git a/src/compas_view2/app/controller.py b/src/compas_view2/app/controller.py index fe1b6bd38..54d1308ab 100644 --- a/src/compas_view2/app/controller.py +++ b/src/compas_view2/app/controller.py @@ -123,13 +123,13 @@ def mouse_key_check(self, event, key_status: Dict, mouse_key: Dict): The dictionary that is like `"mouse_key": { "mouse": "right", "key": "shift" }`. Returns - ---------- - bool: + ------- + bool If the mouse key is happening. Notes - ---------- + ----- This function is designed to check mouse_key combine interactions. The interactions are: "box_selection", "selection", "multi_selection", "deselect", "pan", "rotate", for now. """ @@ -166,8 +166,8 @@ def mouse_check(self, event, button_name: str): The name of the button. It should be exist in the list of `supported buttons`. Returns - ---------- - bool: + ------- + bool If the button is pressed. """ supported_buttons = { @@ -197,8 +197,8 @@ def key_check(self, event, key_status: Dict, key_name: str): The name of the key. It should be exist in the list of `supported keys`. Returns - ---------- - bool: + ------- + bool If the key is pressed. """ @@ -224,8 +224,8 @@ def keys_pressed_check(self, action, event): event : QKeyEvent Returns - ---------- - bool: + ------- + bool If all the keys are pressed. """ for key in self.keys[action]: @@ -247,8 +247,8 @@ def keys_released_check(self, action, event): event : QKeyEvent Returns - ---------- - bool: + ------- + bool If all the keys are released. """ for key in self.keys[action]: