Page not found
+
+
+
+
+
+ {{ body }}
+
+
+  }})
+
+
+
+ Sorry, but the documentation page that you are looking for was not found.
\n\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', +} + +# 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' + +############################################################ +### General configuration +############################################################ + +exclude_patterns = [ + '_build', + 'Thumbs.db', + '.DS_Store', + '.sphinx', +] +exclude_patterns.extend(custom_excludes) + +rst_epilog = ''' +.. include:: /reuse/links.txt +''' +if 'custom_rst_epilog' in locals(): + rst_epilog = custom_rst_epilog + +if 'custom_manpages_url' in locals(): + manpages_url = custom_manpages_url +else: + manpages_distribution = subprocess.check_output("distro-info --stable", + text=True, shell=True).strip() + manpages_url = ("https://manpages.ubuntu.com/manpages/" + f"{manpages_distribution}/en/" + "man{section}/{page}.{section}.html") + +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +if not 'conf_py_path' in html_context and 'github_folder' in html_context: + html_context['conf_py_path'] = html_context['github_folder'] + +# 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) + +# Tags cannot be added directly in custom_conf.py, so add them here +for tag in custom_tags: + tags.add(tag) + +# html_context['get_contribs'] is a function and cannot be +# cached (see https://github.com/sphinx-doc/sphinx/issues/12300) +suppress_warnings = ["config.cache"] + +############################################################ +### Styling +############################################################ + +# Find the current builder +builder = 'dirhtml' +if '-b' in sys.argv: + builder = sys.argv[sys.argv.index('-b')+1] + +# Setting templates_path for epub makes the build fail +if builder == 'dirhtml' or builder == 'html': + templates_path = ['.sphinx/_templates'] + notfound_template = '404.html' + +# Theme configuration +html_theme = 'furo' +html_last_updated_fmt = '' +html_permalinks_icon = '¶' + +if html_title == '': + html_theme_options = { + 'sidebar_hide_name': True + } + +############################################################ +### Additional files +############################################################ + +html_static_path = ['.sphinx/_static'] + +html_css_files = [ + 'custom.css', + 'header.css', + 'github_issue_links.css', + 'furo_colors.css', + 'footer.css' +] +html_css_files.extend(custom_html_css_files) + +html_js_files = ['header-nav.js', 'footer.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) + +############################################################# +# Display the contributors + +def get_contributors_for_file(github_url, github_folder, pagename, page_source_suffix, display_contributors_since=None): + filename = f"{pagename}{page_source_suffix}" + paths=html_context['github_folder'][1:] + filename + repo = Repo("../") + since = display_contributors_since if display_contributors_since and display_contributors_since.strip() else None + + commits = repo.iter_commits(paths=paths, since=since) + + contributors_dict = {} + for commit in commits: + contributor = commit.author.name + if contributor not in contributors_dict or commit.committed_date > contributors_dict[contributor]['date']: + contributors_dict[contributor] = { + 'date': commit.committed_date, + 'sha': commit.hexsha + } + # The github_page contains the link to the contributor's latest commit. + contributors_list = [{'name': name, 'github_page': f"{github_url}/commit/{data['sha']}"} for name, data in contributors_dict.items()] + sorted_contributors_list = sorted(contributors_list, key=lambda x: x['name']) + return sorted_contributors_list + +html_context['get_contribs'] = get_contributors_for_file +############################################################# diff --git a/docs/custom_conf.py b/docs/custom_conf.py new file mode 100644 index 000000000..616a2eba5 --- /dev/null +++ b/docs/custom_conf.py @@ -0,0 +1,217 @@ +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 = 'Documentation starter pack' +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