diff --git a/doc/source/conf.py b/doc/source/conf.py index ce646a1d..18303cf8 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,7 +22,7 @@ # Project information project = "ansys_sphinx_theme" copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved" -author = "Ansys Inc." +author = "ANSYS, Inc." release = version = __version__ cname = os.getenv("DOCUMENTATION_CNAME", "nocname.com") @@ -40,7 +40,6 @@ # specify the location of your github repo html_theme_options = { "github_url": "https://github.com/ansys/ansys-sphinx-theme", - "use_edit_page_button": True, "contact_mail": "pyansys.support@ansys.com", "additional_breadcrumbs": [ ("Ansys Internal Developer Portal", "https://dev.docs.ansys.com"), @@ -55,7 +54,6 @@ "json_url": f"https://{cname}/release/versions.json", "version_match": get_version_match(__version__), }, - "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"], } html_short_title = html_title = "Ansys Sphinx Theme" diff --git a/pyproject.toml b/pyproject.toml index 4d8d748a..14866d18 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -46,12 +46,11 @@ name = "ansys_sphinx_theme" [tool.flit.sdist] include = [ - "src/ansys_sphinx_theme/layout.html", - "src/ansys_sphinx_theme/breadcrumbs.html", - "src/ansys_sphinx_theme/docs-navbar.html", - "src/ansys_sphinx_theme/theme.conf", - "src/ansys_sphinx_theme/_templates/", - "src/ansys_sphinx_theme/static/", + "src/ansys_sphinx_theme/theme/ansys_sphinx_theme/layout.html", + "src/ansys_sphinx_theme/theme/ansys_sphinx_theme/components/breadcrumbs.html", + "src/ansys_sphinx_theme/theme/ansys_sphinx_theme/theme.conf", + "src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/", + "src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/", ] [project.urls] diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 26774d82..fbd6214c 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -1,55 +1,115 @@ """This is the ansys-sphinx-theme module.""" -import os -from pathlib import Path +import pathlib +from typing import Dict + +import sphinx from ansys_sphinx_theme.latex import generate_404 # noqa: F401 __version__ = "0.9.dev0" -# get location of this directory -_this_path = os.path.dirname(os.path.realpath(__file__)) + +# Declare the fundamental paths of the theme +THIS_PATH = pathlib.Path(__file__).parent.resolve() +THEME_PATH = THIS_PATH / "theme" / "ansys_sphinx_theme" +STATIC_PATH = THEME_PATH / "static" +STYLE_PATH = STATIC_PATH / "css" +CSS_PATH = STYLE_PATH / "ansys_sphinx_theme.css" +TEMPLATES_PATH = THEME_PATH / "_templates" # make logo paths available -pyansys_logo_black = os.path.join(_this_path, "static", "pyansys-logo-black-cropped.png") -pyansys_logo_white = os.path.join(_this_path, "static", "pyansys-logo-white-cropped.png") -ansys_favicon = os.path.join(_this_path, "static", "ansys-favicon.png") -ansys_logo_white = os.path.join(_this_path, "static", "ansys_logo_white.pdf") -ansys_logo_white_cropped = os.path.join(_this_path, "static", "ansys_logo_white_cropped.pdf") -watermark = os.path.join(_this_path, "static", "watermark.pdf") -ansys_logo_black = os.path.join(_this_path, "static", "ansys_logo_black_cropped.jpg") +ansys_favicon = str((STATIC_PATH / "ansys-favicon.png").absolute()) +ansys_logo_black = str((STATIC_PATH / "ansys_logo_black_cropped.jpg").absolute()) +ansys_logo_white = str((STATIC_PATH / "ansys_logo_white.pdf").absolute()) +ansys_logo_white_cropped = str((STATIC_PATH / "ansys_logo_white_cropped.pdf").absolute()) +page_404 = str((STATIC_PATH / "404.rst").absolute()) +pyansys_logo_black = str((STATIC_PATH / "pyansys-logo-black-cropped.png").absolute()) +pyansys_logo_white = str((STATIC_PATH / "pyansys-logo-white-cropped.png").absolute()) +watermark = str((STATIC_PATH / "watermark.pdf").absolute()) + + +def get_html_theme_path() -> pathlib.Path: + """Return list of HTML theme paths. -# Enable default 404 page -page_404 = os.path.join(_this_path, "static", "404.rst") + Returns + ------- + pathlib.Path + Path pointing to the installation directory of the theme. -html_logo = pyansys_logo_black -CSS_FILENAME = "ansys_sphinx_theme.css" + """ + return THEME_PATH.resolve() -def get_html_theme_path(): - """Return list of HTML theme paths.""" - return Path(__file__).parents[0].absolute() +def get_version_match(semver: str) -> str: + """Evaluate the version match for the multi-documentation. + Parameters + ---------- + semver : str + Semantic version number in the form of a string. -def get_version_match(semver): - """Evaluate the version match for the multi-documentation.""" + Returns + ------- + str + Matching version number in the form of a string. + + """ if semver.endswith("dev0"): return "dev" major, minor, _ = semver.split(".") return ".".join([major, minor]) -def setup(app): - """Connect to the sphinx theme app.""" +def setup_default_html_theme_options(app): + """Set up the default configuration for the HTML options. + + Parameters + ---------- + app : sphinx.application.Sphinx + Application instance for rendering the documentation. + + Notes + ----- + This function is the only way to overwrite ``pydata-sphinx-theme`` + configuration. Variables declared in the ``theme.conf`` do not include + inherited ones. + + """ + # Place all switchers and icons at the end of the navigation bar + app.config.html_theme_options.setdefault( + "navbar_end", ["version-switcher", "theme-switcher", "navbar-icon-links"] + ) + + +def setup(app: sphinx.application.Sphinx) -> Dict: + """Connect to the sphinx theme app. + + Parameters + ---------- + app : sphinx.application.Sphinx + Application instance for rendering the documentation. + + Returns + ------- + Dict + Dictionary containing application status. + + """ + # Add the theme configuration theme_path = get_html_theme_path() app.add_html_theme("ansys_sphinx_theme", theme_path) - theme_css_path = theme_path / "static" / "css" / CSS_FILENAME - if not theme_css_path.exists(): - raise FileNotFoundError(f"Unable to locate ansys-sphinx theme at {theme_css_path}") - app.add_css_file(str(theme_css_path.relative_to(theme_path / "static"))) - - # add templates for autosummary - path_templates = os.path.join(_this_path, "_templates") - app.config.templates_path.append(path_templates) + app.config.templates_path.append(str(THEME_PATH / "components")) + + # Add default HTML configuration + setup_default_html_theme_options(app) + + # Verify that the main CSS file exists + if not CSS_PATH.exists(): + raise FileNotFoundError(f"Unable to locate ansys-sphinx theme at {CSS_PATH.absolute()}") + app.add_css_file(str(CSS_PATH.relative_to(STATIC_PATH))) + + # Add templates for autosummary + app.config.templates_path.append(str(TEMPLATES_PATH)) return { "version": __version__, diff --git a/src/ansys_sphinx_theme/docs-navbar.html b/src/ansys_sphinx_theme/docs-navbar.html deleted file mode 100644 index 71f8d3be..00000000 --- a/src/ansys_sphinx_theme/docs-navbar.html +++ /dev/null @@ -1,41 +0,0 @@ - - -
- - - - - - {% set navbar_class, navbar_align = navbar_align_class() %} - -
diff --git a/src/ansys_sphinx_theme/examples/__init__.py b/src/ansys_sphinx_theme/examples/__init__.py new file mode 100644 index 00000000..3edab9b2 --- /dev/null +++ b/src/ansys_sphinx_theme/examples/__init__.py @@ -0,0 +1 @@ +"""A sub-package containing various examples for checking their rendering.""" diff --git a/src/ansys_sphinx_theme/sample_func.py b/src/ansys_sphinx_theme/examples/sample_func.py similarity index 100% rename from src/ansys_sphinx_theme/sample_func.py rename to src/ansys_sphinx_theme/examples/sample_func.py diff --git a/src/ansys_sphinx_theme/samples.py b/src/ansys_sphinx_theme/examples/samples.py similarity index 100% rename from src/ansys_sphinx_theme/samples.py rename to src/ansys_sphinx_theme/examples/samples.py diff --git a/src/ansys_sphinx_theme/type_hint_example.py b/src/ansys_sphinx_theme/examples/type_hint_example.py similarity index 100% rename from src/ansys_sphinx_theme/type_hint_example.py rename to src/ansys_sphinx_theme/examples/type_hint_example.py diff --git a/src/ansys_sphinx_theme/icon-links.html b/src/ansys_sphinx_theme/icon-links.html deleted file mode 100644 index f893de37..00000000 --- a/src/ansys_sphinx_theme/icon-links.html +++ /dev/null @@ -1,27 +0,0 @@ -{%- macro icon_link_nav_item(url, icon, name, type) -%} - {%- if (url | length > 2) and name not in theme_hidden_icons %} - - {%- endif -%} -{%- endmacro -%} - - diff --git a/src/ansys_sphinx_theme/_templates/autosummary/base.rst b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autosummary/base.rst similarity index 100% rename from src/ansys_sphinx_theme/_templates/autosummary/base.rst rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autosummary/base.rst diff --git a/src/ansys_sphinx_theme/_templates/autosummary/class.rst b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autosummary/class.rst similarity index 100% rename from src/ansys_sphinx_theme/_templates/autosummary/class.rst rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autosummary/class.rst diff --git a/src/ansys_sphinx_theme/announcement_layout.html b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/components/announcement_version.html similarity index 91% rename from src/ansys_sphinx_theme/announcement_layout.html rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/components/announcement_version.html index 96e868e8..5feeeeb0 100644 --- a/src/ansys_sphinx_theme/announcement_layout.html +++ b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/components/announcement_version.html @@ -1,4 +1,3 @@ -{% if theme_switcher %}
-{% endif %} diff --git a/src/ansys_sphinx_theme/breadcrumbs.html b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/components/breadcrumbs.html similarity index 100% rename from src/ansys_sphinx_theme/breadcrumbs.html rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/components/breadcrumbs.html diff --git a/src/ansys_sphinx_theme/layout.html b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/layout.html similarity index 87% rename from src/ansys_sphinx_theme/layout.html rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/layout.html index 839fe6bd..6c6c32a7 100644 --- a/src/ansys_sphinx_theme/layout.html +++ b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/layout.html @@ -26,9 +26,12 @@ {% block docs_navbar %} {{ super() }} - {% include 'announcement_layout.html' %} + + {% if theme_switcher %} + {% include 'components/announcement_version.html' %} + {% endif %} + {% if theme_show_breadcrumbs %} - {% include 'breadcrumbs.html' %} + {% include 'components/breadcrumbs.html' %} {% endif %} {% endblock %} - diff --git a/src/ansys_sphinx_theme/static/404.rst b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/404.rst similarity index 100% rename from src/ansys_sphinx_theme/static/404.rst rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/404.rst diff --git a/src/ansys_sphinx_theme/static/ansys-favicon.png b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/ansys-favicon.png similarity index 100% rename from src/ansys_sphinx_theme/static/ansys-favicon.png rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/ansys-favicon.png diff --git a/src/ansys_sphinx_theme/static/ansys_logo_black.jpg b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/ansys_logo_black.jpg similarity index 100% rename from src/ansys_sphinx_theme/static/ansys_logo_black.jpg rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/ansys_logo_black.jpg diff --git a/src/ansys_sphinx_theme/static/ansys_logo_black_cropped.jpg b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/ansys_logo_black_cropped.jpg similarity index 100% rename from src/ansys_sphinx_theme/static/ansys_logo_black_cropped.jpg rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/ansys_logo_black_cropped.jpg diff --git a/src/ansys_sphinx_theme/static/ansys_logo_white.pdf b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/ansys_logo_white.pdf similarity index 100% rename from src/ansys_sphinx_theme/static/ansys_logo_white.pdf rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/ansys_logo_white.pdf diff --git a/src/ansys_sphinx_theme/static/ansys_logo_white_cropped.pdf b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/ansys_logo_white_cropped.pdf similarity index 100% rename from src/ansys_sphinx_theme/static/ansys_logo_white_cropped.pdf rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/ansys_logo_white_cropped.pdf diff --git a/src/ansys_sphinx_theme/static/css/ansys_sphinx_theme.css b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/css/ansys_sphinx_theme.css similarity index 100% rename from src/ansys_sphinx_theme/static/css/ansys_sphinx_theme.css rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/css/ansys_sphinx_theme.css diff --git a/src/ansys_sphinx_theme/static/css/breadcrumbs.css b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/css/breadcrumbs.css similarity index 100% rename from src/ansys_sphinx_theme/static/css/breadcrumbs.css rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/css/breadcrumbs.css diff --git a/src/ansys_sphinx_theme/static/fonts/SourceSansPro-Light.ttf b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/fonts/SourceSansPro-Light.ttf similarity index 100% rename from src/ansys_sphinx_theme/static/fonts/SourceSansPro-Light.ttf rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/fonts/SourceSansPro-Light.ttf diff --git a/src/ansys_sphinx_theme/static/fonts/SourceSansPro-Regular.ttf b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/fonts/SourceSansPro-Regular.ttf similarity index 100% rename from src/ansys_sphinx_theme/static/fonts/SourceSansPro-Regular.ttf rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/fonts/SourceSansPro-Regular.ttf diff --git a/src/ansys_sphinx_theme/static/fonts/SourceSansPro-SemiBold.ttf b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/fonts/SourceSansPro-SemiBold.ttf similarity index 100% rename from src/ansys_sphinx_theme/static/fonts/SourceSansPro-SemiBold.ttf rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/fonts/SourceSansPro-SemiBold.ttf diff --git a/src/ansys_sphinx_theme/static/js/download_target_blank.js b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/js/download_target_blank.js similarity index 100% rename from src/ansys_sphinx_theme/static/js/download_target_blank.js rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/js/download_target_blank.js diff --git a/src/ansys_sphinx_theme/static/pyansys-logo-black-cropped.png b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys-logo-black-cropped.png similarity index 100% rename from src/ansys_sphinx_theme/static/pyansys-logo-black-cropped.png rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys-logo-black-cropped.png diff --git a/src/ansys_sphinx_theme/static/pyansys-logo-white-cropped.png b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys-logo-white-cropped.png similarity index 100% rename from src/ansys_sphinx_theme/static/pyansys-logo-white-cropped.png rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys-logo-white-cropped.png diff --git a/src/ansys_sphinx_theme/static/pyansys_dark.png b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys_dark.png similarity index 100% rename from src/ansys_sphinx_theme/static/pyansys_dark.png rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys_dark.png diff --git a/src/ansys_sphinx_theme/static/pyansys_dark_square.png b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys_dark_square.png similarity index 100% rename from src/ansys_sphinx_theme/static/pyansys_dark_square.png rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys_dark_square.png diff --git a/src/ansys_sphinx_theme/static/pyansys_light.png b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys_light.png similarity index 100% rename from src/ansys_sphinx_theme/static/pyansys_light.png rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys_light.png diff --git a/src/ansys_sphinx_theme/static/pyansys_light_square.png b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys_light_square.png similarity index 100% rename from src/ansys_sphinx_theme/static/pyansys_light_square.png rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys_light_square.png diff --git a/src/ansys_sphinx_theme/static/watermark.pdf b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/watermark.pdf similarity index 100% rename from src/ansys_sphinx_theme/static/watermark.pdf rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/watermark.pdf diff --git a/src/ansys_sphinx_theme/theme.conf b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/theme.conf similarity index 86% rename from src/ansys_sphinx_theme/theme.conf rename to src/ansys_sphinx_theme/theme/ansys_sphinx_theme/theme.conf index 069fe209..f0112da9 100644 --- a/src/ansys_sphinx_theme/theme.conf +++ b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/theme.conf @@ -10,4 +10,5 @@ show_breadcrumbs = True show_icons = True hidden_icons = additional_breadcrumbs = -switcher = \ No newline at end of file +use_edit_page_button = True +switcher =