-
-
--
-
-
-
-
-
-
{{ project }} -- -
-
-
-
- - - More resources - - - -
Sorry, but the documentation page that you are looking for was not found.
\nDocumentation changes over time, and pages are moved around. We try to redirect you to the updated content where possible, but unfortunately, that didn\'t work this time (maybe because the content you were looking for does not exist in this version of the documentation).
\nYou can try to use the navigation to locate the content you\'re looking for, or search for a similar page.
\n', -} +# Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html) +# For example: 'explanation/old-name.html': '../how-to/prettify.html', + +redirects = {} + +############################################################ +### Link checker exceptions +############################################################ + +# Links to ignore when checking links + +linkcheck_ignore = ["http://127.0.0.1:8000"] -# Default image for OGP (to prevent font errors, see -# https://github.com/canonical/sphinx-docs-starter-pack/pull/54 ) -if not 'ogp_image' in locals(): - ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg' +# Pages on which to ignore anchors +# (This list will be appended to linkcheck_anchors_ignore_for_url) + +custom_linkcheck_anchors_ignore_for_url = [] ############################################################ -### General configuration +### Additions to default configuration ############################################################ +## The following settings are appended to the default configuration. +## Use them to extend the default functionality. + +# Add extensions +extensions = [ + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinx.ext.coverage", + "sphinx.ext.doctest", + "sphinx_design", + "sphinx_copybutton", + "sphinx-pydantic", + "sphinx.ext.autodoc", + "sphinx_toolbox", + "sphinx_starter_pack", +] + +# Add MyST extensions +myst_extensions = [] + +# Add files or directories that should be excluded from processing. exclude_patterns = [ - '_build', - 'Thumbs.db', - '.DS_Store', - '.sphinx', + "doc-cheat-sheet*", ] -exclude_patterns.extend(custom_excludes) -rst_epilog = ''' -.. include:: /reuse/links.txt -''' -if 'custom_rst_epilog' in locals(): - rst_epilog = custom_rst_epilog +# Add CSS files (located in .sphinx/_static/) +html_css_files = [] -source_suffix = { - '.rst': 'restructuredtext', - '.md': 'markdown', -} +# Add JavaScript files (located in .sphinx/_static/) +html_js_files = [] -if not 'conf_py_path' in html_context and 'github_folder' in html_context: - html_context['conf_py_path'] = html_context['github_folder'] +## The following settings override the default configuration. -# For ignoring specific links -linkcheck_anchors_ignore_for_url = [ - r'https://github\.com/.*' -] -linkcheck_anchors_ignore_for_url.extend(custom_linkcheck_anchors_ignore_for_url) +# Specify a reST string that is included at the end of each file. +# If commented out, use the default (which pulls the reuse/links.txt +# file into each reST file). +# custom_rst_epilog = '' + +# By default, the documentation includes a feedback button at the top. +# You can disable it by setting the following configuration to True. +disable_feedback_button = False -# Tags cannot be added directly in custom_conf.py, so add them here -for tag in custom_tags: - tags.add(tag) +# Add tags that you want to use for conditional inclusion of text +# (https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#tags) +tags = [] ############################################################ -### Styling +### Additional configuration ############################################################ -# Find the current builder -builder = 'dirhtml' -if '-b' in sys.argv: - builder = sys.argv[sys.argv.index('-b')+1] +## Add any configuration that is not covered by the common conf.py file. -# Setting templates_path for epub makes the build fail -if builder == 'dirhtml' or builder == 'html': - templates_path = ['.sphinx/_templates'] +linkcheck_ignore += [r"craft_cli.dispatcher.html#craft_cli.dispatcher.CommandGroup"] -# Theme configuration -html_theme = 'furo' -html_last_updated_fmt = '' -html_permalinks_icon = '¶' +# Type hints configuration +set_type_checking_flag = True +typehints_fully_qualified = False +always_document_param_types = True +typehints_document_rtype = True -if html_title == '': - html_theme_options = { - 'sidebar_hide_name': True - } +# Github config +github_username = "canonical" +github_repository = "craft-cli" +# endregion -############################################################ -### Additional files -############################################################ +# Document class properties before public methods +autodoc_member_order = "bysource" -html_static_path = ['.sphinx/_static'] -html_css_files = [ - 'custom.css', - 'header.css', - 'github_issue_links.css', - 'furo_colors.css' -] -html_css_files.extend(custom_html_css_files) +# region Setup reference generation +def run_apidoc(_): + from sphinx.ext.apidoc import main + import os + import sys + + sys.path.append(os.path.join(os.path.dirname(__file__), "..")) + cur_dir = os.path.abspath(os.path.dirname(__file__)) + module = os.path.join(cur_dir, "..", "craft_cli") + exclude_patterns = ["*pytest_plugin*"] + main(["-e", "--no-toc", "--force", "-o", cur_dir, module, *exclude_patterns]) + + +def no_namedtuple_attrib_docstring(app, what, name, obj, options, lines): + """Strips out silly "Alias for field number" lines in namedtuples reference.""" + if len(lines) == 1 and lines[0].startswith("Alias for field number"): + del lines[:] + + +def setup(app): + app.connect("builder-inited", run_apidoc) + app.connect("autodoc-process-docstring", no_namedtuple_attrib_docstring) + -html_js_files = ['header-nav.js'] -if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button: - html_js_files.append('github_issue_links.js') -html_js_files.extend(custom_html_js_files) +# endregion diff --git a/docs/custom_conf.py b/docs/custom_conf.py deleted file mode 100644 index c0b144d..0000000 --- a/docs/custom_conf.py +++ /dev/null @@ -1,213 +0,0 @@ -import datetime - -# Custom configuration for the Sphinx documentation builder. -# All configuration specific to your project should be done in this file. -# -# The file is included in the common conf.py configuration file. -# You can modify any of the settings below or add any configuration that -# is not covered by the common conf.py file. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html -# -# If you're not familiar with Sphinx and don't want to use advanced -# features, it is sufficient to update the settings in the "Project -# information" section. - -############################################################ -### Project information -############################################################ - -# Product name -project = "Craft CLI" -author = "Canonical Group Ltd" - -# The title you want to display for the documentation in the sidebar. -# You might want to include a version number here. -# To not display any title, set this option to an empty string. -html_title = project + " documentation" - -# The default value uses the current year as the copyright year. -# -# For static works, it is common to provide the year of first publication. -# Another option is to give the first year and the current year -# for documentation that is often changed, e.g. 2022–2023 (note the en-dash). -# -# A way to check a GitHub repo's creation date is to obtain a classic GitHub -# token with 'repo' permissions here: https://github.com/settings/tokens -# Next, use 'curl' and 'jq' to extract the date from the GitHub API's output: -# -# curl -H 'Authorization: token