Sphinx book theme

[ZacZhangzhuo]

What type of change is this?

• [ ] Try to use the Sphinx book theme. I am kind of getting there:

Issues

• [ ] The build process is very very slow. I think this web could help: https://docs.readthedocs.io/en/stable/guides/build-using-too-many-resources.html.
• [ ] The generated folder in the api is apparently old since the API has been updated. Could you teach me how to regenerate? @Licini

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• [x] I added a line to the CHANGELOG.md file in the Unreleased section under the most fitting heading (e.g. Added, Changed, Removed).
• [x] I ran all tests on my computer and it's all green (i.e. invoke test).
• [x] I ran lint on my computer and there are no errors (i.e. invoke lint).
• [ ] I added new functions/classes and made them available on a second-level import, e.g. compas.datastructures.Mesh.
• [x] I have added tests that prove my fix is effective or that my feature works.
• [x] I have added necessary documentation (if appropriate)

[ZacZhangzhuo]

wait for the update of the sphinx-compas-theme

[tomvanmele]

sphinx_compas2_theme is now available

[tomvanmele]

dev requirements can be reduced to

attrs >=17.4
black ==22.12.0
bump2version >=1.0.1
check-manifest >=0.36
compas_invocations
doc8
flake8
invoke >=0.14
isort
sphinx_compas2_theme
twine
wheel
-e .

[tomvanmele]

you can remove the templates folder and all static images and use the following conf.py

# flake8: noqa
# -*- coding: utf-8 -*-

from sphinx.writers import html, html5
import sphinx_compas2_theme

# -- General configuration ------------------------------------------------

project = "COMPAS View2"
copyright = "COMPAS Association"
author = "..."
organization = "compas-dev"
package = "compas_view2"

master_doc = "index"
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"

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_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 = {}
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 = "groupwise"
autodoc_typehints = "description"
autodoc_class_signature = "separated"

autoclass_content = "class"

def setup(app):
    app.connect("autodoc-skip-member", sphinx_compas2_theme.skip)

# autosummary options

autosummary_generate = True
autosummary_mock_imports = sphinx_compas2_theme.default_mock_imports

# graph options

# plot options

plot_include_source = False
plot_html_show_source_link = False
plot_html_show_formats = False
plot_formats = ["png"]

# intersphinx options

intersphinx_mapping = {
    "python": ("https://docs.python.org/", None),
    "compas": ("https://compas.dev/compas/latest/", None),
}

# linkcode

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 = "sidebaronly"
html_title = project

favicons = [
    {
        "rel": "icon",
        "href": "compas.ico",  # relative to the static path
    }
]

html_theme_options = {
    "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_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 = True
html_permalinks = False
html_permalinks_icon = ""
html_compact_lists = True

[ZacZhangzhuo]

build success, title lines are fixed, and the bases are linked.