From 86fae8e7f6445b0f90bedfe54930529c3d1e1309 Mon Sep 17 00:00:00 2001 From: Ruth Fuchss Date: Fri, 7 Jul 2023 15:30:53 +0200 Subject: [PATCH] split the configuration file into common and custom Put the common configuration in one file and all project-specific configuration into another one, so that users can easily update the common configuration while keeping their customisations. This also makes it much easier to update the project-specific configuration. Fixes #39 and #47. Signed-off-by: Ruth Fuchss --- conf.py | 213 +++++++++++++++++++++++-------------------------- custom_conf.py | 122 ++++++++++++++++++++++++++++ readme.rst | 50 +++++------- 3 files changed, 240 insertions(+), 145 deletions(-) create mode 100644 custom_conf.py diff --git a/conf.py b/conf.py index d890dd82..8a26bf29 100644 --- a/conf.py +++ b/conf.py @@ -1,52 +1,19 @@ -import datetime import sys +sys.path.append('./') +from custom_conf import * + # Configuration file for the Sphinx documentation builder. +# You should not do any modifications to this file. Put your custom +# configuration into the custom_conf.py file. +# If you need to change this file, contribute the changes upstream. # # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = 'Documentation starter pack' -author = 'Canonical Group Ltd' -copyright = "%s, %s" % (datetime.date.today().year, author) -release = '1.0' - -# Open Graph configuration - defines what is displayed in the website preview -ogp_site_url = "https://canonical-starter-pack.readthedocs-hosted.com/" -ogp_site_name = project -ogp_image = "https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg" - -# Update with the favicon for your product -html_favicon = ".sphinx/_static/favicon.png" - -html_context = { - # Change to the link to your product website (without "https://") - "product_page": "documentation.ubuntu.com", - # Add your product tag to ".sphinx/_static" and change the path - # here (start with "/static") - "product_tag": "/_static/tag.png", - # Change to the discourse instance you want to be able to link to - # (use an empty value if you don't want to link) - "discourse": "https://discourse.ubuntu.com", - # Change to the GitHub info for your project - "github_url": "https://github.com/canonical/starter-pack", - # Change to the branch for this version of the documentation - "github_version": "main", - # Change to the folder that contains the documentation (usually "/" or "/docs/") - "github_folder": "/", - # Change to an empty value if your GitHub repo doesn't have issues enabled - "github_issues": "enabled" -} - -# Used for related links - no need to change -if 'discourse' in html_context: - html_context['discourse_prefix'] = html_context['discourse'] + "/t/" - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration +############################################################ +### Extensions +############################################################ extensions = [ 'sphinx_design', @@ -61,112 +28,128 @@ 'myst_parser', 'sphinxcontrib.jquery' ] +extensions.extend(custom_extensions) + +### Configuration for extensions +# Additional MyST syntax myst_enable_extensions = [ - "substitution", - "deflist" + 'substitution', + 'deflist' ] +# Used for related links +if 'discourse' in html_context: + html_context['discourse_prefix'] = html_context['discourse'] + '/t/' + +############################################################ +### General configuration +############################################################ + exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.sphinx'] +exclude_patterns.extend(custom_excludes) -rst_epilog = """ +rst_epilog = ''' .. include:: /reuse/links.txt -""" +''' +if 'custom_rst_epilog' in locals(): + rst_epilog = custom_rst_epilog source_suffix = { '.rst': 'restructuredtext', '.md': 'markdown', } -# Links to ignore when checking links -linkcheck_ignore = [ - 'http://127.0.0.1:8000' - ] +if not 'conf_py_path' in html_context and 'github_folder' in html_context: + html_context['conf_py_path'] = html_context['github_folder'] -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output +############################################################ +### Styling +############################################################ # Find the current builder -builder = "dirhtml" +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"] +if builder == 'dirhtml' or builder == 'html': + templates_path = ['.sphinx/_templates'] +# Theme configuration html_theme = 'furo' -html_last_updated_fmt = "" -html_permalinks_icon = "¶" +html_last_updated_fmt = '' +html_permalinks_icon = '¶' html_theme_options = { - "light_css_variables": { - "font-stack": "Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif", - "font-stack--monospace": "Ubuntu Mono, Consolas, Monaco, Courier, monospace", - "color-foreground-primary": "#111", - "color-foreground-secondary": "var(--color-foreground-primary)", - "color-foreground-muted": "#333", - "color-background-secondary": "#FFF", - "color-background-hover": "#f2f2f2", - "color-brand-primary": "#111", - "color-brand-content": "#06C", - "color-api-background": "#cdcdcd", - "color-inline-code-background": "rgba(0,0,0,.03)", - "color-sidebar-link-text": "#111", - "color-sidebar-item-background--current": "#ebebeb", - "color-sidebar-item-background--hover": "#f2f2f2", - "toc-font-size": "var(--font-size--small)", - "color-admonition-title-background--note": "var(--color-background-primary)", - "color-admonition-title-background--tip": "var(--color-background-primary)", - "color-admonition-title-background--important": "var(--color-background-primary)", - "color-admonition-title-background--caution": "var(--color-background-primary)", - "color-admonition-title--note": "#24598F", - "color-admonition-title--tip": "#24598F", - "color-admonition-title--important": "#C7162B", - "color-admonition-title--caution": "#F99B11", - "color-highlighted-background": "#EbEbEb", - "color-link-underline": "var(--color-background-primary)", - "color-link-underline--hover": "var(--color-background-primary)", - "color-version-popup": "#772953" + 'light_css_variables': { + 'font-stack': 'Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif', + 'font-stack--monospace': 'Ubuntu Mono, Consolas, Monaco, Courier, monospace', + 'color-foreground-primary': '#111', + 'color-foreground-secondary': 'var(--color-foreground-primary)', + 'color-foreground-muted': '#333', + 'color-background-secondary': '#FFF', + 'color-background-hover': '#f2f2f2', + 'color-brand-primary': '#111', + 'color-brand-content': '#06C', + 'color-api-background': '#cdcdcd', + 'color-inline-code-background': 'rgba(0,0,0,.03)', + 'color-sidebar-link-text': '#111', + 'color-sidebar-item-background--current': '#ebebeb', + 'color-sidebar-item-background--hover': '#f2f2f2', + 'toc-font-size': 'var(--font-size--small)', + 'color-admonition-title-background--note': 'var(--color-background-primary)', + 'color-admonition-title-background--tip': 'var(--color-background-primary)', + 'color-admonition-title-background--important': 'var(--color-background-primary)', + 'color-admonition-title-background--caution': 'var(--color-background-primary)', + 'color-admonition-title--note': '#24598F', + 'color-admonition-title--tip': '#24598F', + 'color-admonition-title--important': '#C7162B', + 'color-admonition-title--caution': '#F99B11', + 'color-highlighted-background': '#EbEbEb', + 'color-link-underline': 'var(--color-background-primary)', + 'color-link-underline--hover': 'var(--color-background-primary)', + 'color-version-popup': '#772953' }, - "dark_css_variables": { - "color-foreground-secondary": "var(--color-foreground-primary)", - "color-foreground-muted": "#CDCDCD", - "color-background-secondary": "var(--color-background-primary)", - "color-background-hover": "#666", - "color-brand-primary": "#fff", - "color-brand-content": "#06C", - "color-sidebar-link-text": "#f7f7f7", - "color-sidebar-item-background--current": "#666", - "color-sidebar-item-background--hover": "#333", - "color-admonition-background": "transparent", - "color-admonition-title-background--note": "var(--color-background-primary)", - "color-admonition-title-background--tip": "var(--color-background-primary)", - "color-admonition-title-background--important": "var(--color-background-primary)", - "color-admonition-title-background--caution": "var(--color-background-primary)", - "color-admonition-title--note": "#24598F", - "color-admonition-title--tip": "#24598F", - "color-admonition-title--important": "#C7162B", - "color-admonition-title--caution": "#F99B11", - "color-highlighted-background": "#666", - "color-link-underline": "var(--color-background-primary)", - "color-link-underline--hover": "var(--color-background-primary)", - "color-version-popup": "#F29879" + 'dark_css_variables': { + 'color-foreground-secondary': 'var(--color-foreground-primary)', + 'color-foreground-muted': '#CDCDCD', + 'color-background-secondary': 'var(--color-background-primary)', + 'color-background-hover': '#666', + 'color-brand-primary': '#fff', + 'color-brand-content': '#06C', + 'color-sidebar-link-text': '#f7f7f7', + 'color-sidebar-item-background--current': '#666', + 'color-sidebar-item-background--hover': '#333', + 'color-admonition-background': 'transparent', + 'color-admonition-title-background--note': 'var(--color-background-primary)', + 'color-admonition-title-background--tip': 'var(--color-background-primary)', + 'color-admonition-title-background--important': 'var(--color-background-primary)', + 'color-admonition-title-background--caution': 'var(--color-background-primary)', + 'color-admonition-title--note': '#24598F', + 'color-admonition-title--tip': '#24598F', + 'color-admonition-title--important': '#C7162B', + 'color-admonition-title--caution': '#F99B11', + 'color-highlighted-background': '#666', + 'color-link-underline': 'var(--color-background-primary)', + 'color-link-underline--hover': 'var(--color-background-primary)', + 'color-version-popup': '#F29879' }, } +############################################################ +### Additional files +############################################################ + html_static_path = ['.sphinx/_static'] + html_css_files = [ 'custom.css', 'header.css', 'github_issue_links.css', ] +html_css_files.extend(custom_html_css_files) html_js_files = ['header-nav.js'] -if "github_issues" in html_context and html_context["github_issues"]: +if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button: html_js_files.append('github_issue_links.js') - - - -# Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html) -# For example: "explanation/old-name.html": "../how-to/prettify.html", -redirects = {} +html_js_files.extend(custom_html_js_files) diff --git a/custom_conf.py b/custom_conf.py new file mode 100644 index 00000000..60e892e9 --- /dev/null +++ b/custom_conf.py @@ -0,0 +1,122 @@ +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 + +############################################################ +### Project information +############################################################ + +# Product name +project = 'Documentation starter pack' +author = 'Canonical Group Ltd' + +# Uncomment if your product uses release numbers +# release = '1.0' + +# The default value uses the current year as the copyright year +copyright = '%s, %s' % (datetime.date.today().year, author) + +## Open Graph configuration - defines what is displayed in the website preview +# The URL of the documentation output +ogp_site_url = 'https://canonical-starter-pack.readthedocs-hosted.com/' +# The documentation website name (usually the same as the product name) +ogp_site_name = project +# An image or logo that is used in the preview +ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg' + +# Update with the favicon for your product (default is the circle of friends) +html_favicon = '.sphinx/_static/favicon.png' + +# (Some settings must be part of the html_context dictionary, while others +# are on root level. Don't move the settings.) +html_context = { + + # Change to the link to your product website (without "https://") + 'product_page': 'documentation.ubuntu.com', + + # Add your product tag to ".sphinx/_static" and change the path + # here (start with "/static"), default is the circle of friends + 'product_tag': '/_static/tag.png', + + # Change to the discourse instance you want to be able to link to + # using the :discourse: metadata at the top of a file + # (use an empty value if you don't want to link) + 'discourse': 'https://discourse.ubuntu.com', + + # Change to the GitHub info for your project + 'github_url': 'https://github.com/canonical/starter-pack', + + # Change to the branch for this version of the documentation + 'github_version': 'main', + + # Change to the folder that contains the documentation + # (usually "/" or "/docs/") + 'github_folder': '/', + + # Change to an empty value if your GitHub repo doesn't have issues enabled. + # This will disable the feedback button and the issue link in the footer. + 'github_issues': 'enabled' +} + +############################################################ +### Redirects +############################################################ + +# 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' + ] + +############################################################ +### Additions to default configuration +############################################################ + +## The following settings are appended to the default configuration. +## Use them to extend the default functionality. + +# Add extensions +custom_extensions = [] + +# Add files or directories that should be excluded from processing. +custom_excludes = [] + +# Add CSS files (located in .sphinx/_static/) +custom_html_css_files = [] + +# Add JavaScript files (located in .sphinx/_static/) +custom_html_js_files = [] + +## The following settings override the default configuration. + +# 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 + +############################################################ +### Additional configuration +############################################################ + +## Add any configuration that is not covered by the common conf.py file. diff --git a/readme.rst b/readme.rst index 7b411a30..060b7771 100644 --- a/readme.rst +++ b/readme.rst @@ -90,38 +90,17 @@ Configure the documentation --------------------------- You must modify some of the default configuration to suit your project. +To simplify keeping your documentation in sync with the starter pack, all custom configuration is located in the ``custom_conf.py`` file. +You should never modify the common ``conf.py`` file. -Add your project information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In ``conf.py``, check or edit the following settings in the *Project information* section: - -* ``project`` -* ``author`` -* ``copyright`` - in most cases, replace the first ``%s`` with the year the project started -* ``release`` - only required if you're actually using release numbers - (beyond the scope of this guide, but you can also use Python to pull this - out of your code itself) -* ``ogp_site_url`` - the URL of the documentation output (needed to generate a preview when linking from another website) -* ``ogp_site_name`` - the title you want to use for the documentation in previews on other websites (by default, this is set to the project name) -* ``ogp_image`` - an image that will be used in the preview on other websites -* ``html_favicon`` - the favicon for the documentation (circle of friends by default) - -In the ``html_context`` variable, update the following settings: - -* ``product_page`` - the address of your product website (without ``https://``) -* ``product_tag`` - the tag image of your product (circle of friends by default) -* ``discourse`` - the URL to the Discourse instance your project uses (needed to add links to posts using the ``:discourse:`` metadata at the top of a file) -* ``github_url`` - the link to your GitHub repository (needed to create the Edit link in the footer and the feedback button) -* ``github_version`` - the branch that contains this version of the documentation -* ``github_folder`` - the folder that contains the documentation files +Go through all settings in the ``Project information`` section of the ``custom_conf.py`` file and update them for your project. -Save ``conf.py``. +See the following sections for further customisation. Configure the header ~~~~~~~~~~~~~~~~~~~~ -By default, the header contains your product tag, product name (taken from the ``project`` setting), a link to your product page, and a drop-down menu for "More resources" that contains links to Discourse and GitHub. +By default, the header contains your product tag, product name (taken from the ``project`` setting in the ``custom_conf.py`` file), a link to your product page, and a drop-down menu for "More resources" that contains links to Discourse and GitHub. You can change any of those links or add further links to the "More resources" drop-down by editing the ``.sphinx/_templates/header.html`` file. For example, you might want to add links to announcements, tutorials, getting started guides, or videos that are not part of the documentation. @@ -139,8 +118,7 @@ Configure the link check If you have links in the documentation that you don't want to be checked (for example, because they are local links or give random errors even though they -work), you can add them to the ``linkcheck_ignore`` variable in the ``conf.py`` -file. +work), you can add them to the ``linkcheck_ignore`` variable in the ``custom_conf.py`` file. Activate/deactivate feedback button ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -151,7 +129,19 @@ populates an issue for them with details of the page they were on when they clicked the button. If your project does not use GitHub issues, set the ``github_issues`` variable -in the ``conf.py`` file to an empty value to disable both the feedback button +in the ``custom_conf.py`` file to an empty value to disable both the feedback button and the issue link in the footer. If you want to deactivate only the feedback button, but keep the link in the -footer, remove the ``github_issue_links.js`` script from the ``conf.py`` file. +footer, set ``disable_feedback_button`` in the ``custom_conf.py`` file to ``True``. + +Add redirects +~~~~~~~~~~~~~ + +You can add redirects to make sure existing links and bookmarks continue working when you move files around. +To do so, specify the old and new paths in the ``redirects`` setting of the ``custom_conf.py`` file. + +Add custom configuration +~~~~~~~~~~~~~~~~~~~~~~~~ + +To add custom configurations for your project, see the ``Additions to default configuration`` and ``Additional configuration`` sections in the ``custom_conf.py`` file. +These can be used to extend or override the common configuration, or to define additional configuration that is not covered by the common ``conf.py`` file.