Merge branch 'main' into 72-reusable-workflow

.github/.jira_sync_config.yaml

@@ -0,0 +1,37 @@
+settings:
+    # Jira project key to create the issue in
+  jira_project_key: "DOCPR"
+
+  # Dictionary mapping GitHub issue status to Jira issue status
+  status_mapping:
+    opened: Untriaged
+    closed: Done
+
+  # (Optional) Jira project components that should be attached to the created issue
+  # Component names are case-sensitive
+  # components:
+  #  - IoT
+  # - DACH TT
+
+  # (Optional) GitHub labels. Only issues with one of those labels will be synchronized.
+  # If not specified, all issues will be synchronized
+  #labels:
+  #  - bug
+  #  - custom
+
+  # (Optional) (Default: false) Add a new comment in GitHub with a link to Jira created issue
+  add_gh_comment: true
+
+  # (Optional) (Default: true) Synchronize issue description from GitHub to Jira
+  sync_description: true
+
+  # (Optional) (Default: true) Synchronize comments from GitHub to Jira
+  sync_comments: true
+
+  # (Optional) (Default: None) Parent Epic key to link the issue to
+  epic_key: "DOCPR-6"
+
+  # (Optional) Dictionary mapping GitHub issue labels to Jira issue types. 
+  # If label on the issue is not in specified list, this issue will be created as a Bug
+  label_mapping:
+    enhancement: Story

.sphinx/requirements.txt

@@ -1,4 +1,4 @@
-sphinx
+sphinx==7.1.2
 sphinx-autobuild
 sphinx-design
 furo

.wordlist.txt

@@ -15,3 +15,4 @@ subtree
 txt
 UI
 yaml
+Jira

conf.py

@@ -85,6 +85,11 @@
 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/.*'
+]
+
 ############################################################
 ### Styling
 ############################################################

custom_conf.py

@@ -21,7 +21,20 @@
 # Uncomment if your product uses release numbers
 # release = '1.0'
 
-# The default value uses the current year as the copyright year
+# 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 <TOKEN>' \
+#   -H 'Accept: application/vnd.github.v3.raw' \
+#   https://api.github.com/repos/canonical/<REPO> | jq '.created_at'
+
 copyright = '%s, %s' % (datetime.date.today().year, author)
 
 ## Open Graph configuration - defines what is displayed in the website preview

readme.rst

@@ -229,6 +229,22 @@ 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.
 
+(Optional) Synchronise GitHub issues to Jira
+--------------------------------------------
+
+If you wish to sync issues from your documentation repository on GitHub to your
+Jira board, configure the `GitHub/Jira sync bot <https://github.com/canonical/gh-jira-sync-bot>`_
+by editing the ``.github/workflows/.jira_sync_config.yaml`` file appropriately.
+In addition to updating this file, you must also apply server configuration
+for this feature to work. For more information, see `server configuration details <https://github.com/canonical/gh-jira-sync-bot#server-configuration>`_
+for the GitHub/Jira sync bot.
+
+The ``.jira_sync_config.yaml`` file that is included in the starter pack
+contains configuration for syncing issues from the starter pack repository to 
+its documentation Jira board.
+Therefore, it does not work out of the box for other repositories in GitHub, 
+and you must update it if you want to use the synchronisation feature.
+
 Change log
 ----------