# IfcOpenShell - IFC toolkit and geometry engine # Copyright (C) 2020-2024 Dion Moult # # This file is part of IfcOpenShell. # # IfcOpenShell is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # IfcOpenShell is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with IfcOpenShell. If not, see . # 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 -------------------------------------------------------------- # 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 sys.path.insert(0, os.path.abspath("..")) # -- Project information ----------------------------------------------------- project = "IfcOpenShell" copyright = "2011-2024 IfcOpenShell Contributors" author = "IfcOpenShell Contributors" # The full version, including alpha/beta/rc tags cwd = os.path.dirname(os.path.realpath(__file__)) with open(os.path.join(cwd, "..", "..", "..", "VERSION"), "r") as f: release = f.read().strip() from docutils import nodes def versioned_link_role(name, rawtext, text, lineno, inliner, options={}, content=[]): url = f"https://github.com/IfcOpenShell/IfcOpenShell/releases/download/ifcopenshell-python-{release}/ifcopenshell-python-{release}-{text}.zip" node = nodes.reference(rawtext, text, refuri=url, **options) return [node], [] def setup(app): app.add_role("ios_python_url", versioned_link_role) # -- 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. # I considered autodoc+autosummary but it had showstopper glitches: # - Some modules couldn't be accessed https://github.com/sphinx-doc/sphinx/issues/7912#issuecomment-1120508738 # - No subnav making it really hard to navigate # - Kinda hacky setup https://stackoverflow.com/questions/2701998/sphinx-autodoc-is-not-automatic-enough # - I couldn't customise the template to show submodules above members which makes API discovery hard for users extensions = ["autoapi.extension", "sphinx.ext.autosectionlabel", "sphinx_copybutton"] # Auto add document prefixes to help guarantee uniqueness of automatic section references. autosectionlabel_prefix_document = True # We'll add the toctree entry ourselves to distinguish between C++ and Python autoapi_add_toctree_entry = True # We're only documenting Python here autoapi_type = "python" # autoapi works by reading source code instead of importing modules autoapi_dirs = ['../ifcopenshell', '../../bcf/src', '../../bsdd', '../../ifccsv', '../../ifcdiff', '../../ifcpatch/ifcpatch', '../../ifctester/ifctester'] # autoapi_dirs = ['../../ifcdiff'] # autoapi_dirs = ['../../ifcdiff', '../ifcopenshell/util'] # autoapi_dirs = ['../../bcf/src', '../../bsdd', '../../ifccsv', '../../ifcdiff', '../../ifcpatch/ifcpatch', '../../ifctester/ifctester'] # These are auto-generated based on the IFC schema, so exclude them autoapi_ignore = ['*ifcopenshell/express/rules*'] # Custom autoapi templates to make it easier to read our docs autoapi_template_dir = "_autoapi_templates" # autoapi_options doesn't have show-module-summary, as it tends to create one # page per function which contradicts the presentation of showing all functions # as a list. This creates two possible locations where a function is documented # which is really disorienting. I also exclude imported-members. For example, # ifcopenshell.file is imported from ifcopenshell.file.file, but it gets pretty # confusing to see the docs again in multiple places (seriously, # ifcopenshell.file.file is everywhere). autoapi_options = ["members", "undoc-members", "show-inheritance", "imported-members"] # This option is set to both to allow both class docstrings and __init__ docstrings. autoapi_python_class_content = "both" # Group by type (e.g. attribute, class, function, etc) then alphabetically. autoapi_member_order = "groupwise" # Add any paths that contain templates here, relative to this directory. 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 HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = "furo" # 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"] html_css_files = ["custom.css"] # Code block styles. Dark styling helps important code examples "pop" on the # page even on light themes. pygments_style = "one-dark" pygments_dark_style = "one-dark" html_logo = "https://ifcopenshell.org/assets/images/logo.png" html_theme_options = { "source_repository": "https://github.com/IfcOpenShell/IfcOpenShell/", "source_branch": "v0.8.0", "source_directory": "src/ifcopenshell-python/docs/", "light_css_variables": { "color-brand-primary": "#39b54a", "color-brand-content": "#39b54a", "color-brand-visited": "#d9e021", "color-background-primary": "#f7f7f6", "color-background-secondary": "#eeeeec", "color-background-border": "#cfd0cb", "color-foreground-primary": "#2e3436", "color-sidebar-item-background--hover": "#f7f7f6", "color-link": "#39b54a", "color-link--visited": "#39b54a", "color-link--hover": "#d98014", "color-link--visited--hover": "#d98014", "font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji", }, "dark_css_variables": { "color-brand-primary": "#39b54a", "color-brand-content": "#39b54a", "color-brand-visited": "#d9e021", "color-background-primary": "#2e3436", "color-background-border": "#2e3436", "color-foreground-primary": "#eeeeec", "color-sidebar-item-background--hover": "#2e3436", "color-link": "#39b54a", "color-link--visited": "#39b54a", "color-link--hover": "#d98014", "color-link--visited--hover": "#d98014", "font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji", }, "footer_icons": [ { "name": "IfcOpenShell", "url": "https://ifcopenshell.org", "html": """ """, "class": "", }, { "name": "GitHub", "url": "https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.8.0/src/ifcopenshell-python/docs", "html": """ """, "class": "", }, ], }