chore: prepare for repository split

.github/workflows/test-starter-pack.yml → .github/workflows/test-sphinx-stack.yml

@@ -1,7 +1,7 @@
-# This workflow tests the starter pack.
-# Don't run this workflow on any repos that use the starter pack.
+# This workflow tests the Sphinx Stack.
+# Don't run this workflow on any repos that use the Sphinx Stack.
 
-name: Test starter pack
+name: Test Sphinx Stack
 
 on:
   push:
@@ -10,7 +10,7 @@ on:
 
 jobs:
   test-docs:
-    name: Test on docs folder
+    name: Test on docs directory
     runs-on: ubuntu-latest
     steps:
     - name: Check out repo

CHANGELOG.md

@@ -8,17 +8,20 @@
 * Remove `reuse/` directory
 * Rename `.sphinx/` directory to `_dev/`
 * Add default configuration for copyright and license statements
+* Remove docs and project-specific configuration
 
 ### Changed
 
-* `docs/conf.py`  [#562](https://github.com/canonical/sphinx-docs-starter-pack/pull/562), [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576), [#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
+* `docs/conf.py`  [#562](https://github.com/canonical/sphinx-docs-starter-pack/pull/562), [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576), [#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590), [#595](https://github.com/canonical/sphinx-docs-starter-pack/pull/595), [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
 * `docs/Makefile` [#575](https://github.com/canonical/sphinx-docs-starter-pack/pull/575), [#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590)
 * `docs/requirements.txt` [#590]([#590](https://github.com/canonical/sphinx-docs-starter-pack/pull/590))
 * `docs/reuse/` [#576](https://github.com/canonical/sphinx-docs-starter-pack/pull/576)
 * `docs/.sphinx/` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
 * `docs/_templates/footer.html` [#594](https://github.com/canonical/sphinx-docs-starter-pack/pull/594)
 * `docs/requirements.txt` [#596](https://github.com/canonical/sphinx-docs-starter-pack/pull/596)
 * `docs/redirects.txt` [#598](https://github.com/canonical/sphinx-docs-starter-pack/pull/598)
+* `docs/.sphinx/update_sp.py` [#595](https://github.com/canonical/sphinx-docs-starter-pack/pull/595)
+* `.github/workflows/test-sphinx-stack.yml` [#595](https://github.com/canonical/sphinx-docs-starter-pack/pull/595)
 
 ## 1.6
 

LICENSE

@@ -1,13 +1,3 @@
-License for Canonical Starter Pack
-==================================
-
-Unless otherwise stated, all code in this repository is licensed under
-the following GPL license.
-Documentation for this project is licensed under CC-BY-SA 3.0.
-
-Starter Pack code
------------------
-
                     GNU GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 
@@ -682,13 +672,3 @@ may consider it more useful to permit linking proprietary applications with
 the library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.  But first, please read
 <https://www.gnu.org/licenses/why-not-lgpl.html>.
-
-Starter Pack documentation
---------------------------
-
-Copyright 2024 Canonical Ltd.
-
-This work is licensed under the Creative Commons Attribution-Share Alike 3.0
-Unported License. To view a copy of this license, visit
-http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative
-Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.

README.md

@@ -1,41 +1,63 @@
-# Canonical's Sphinx Starter Pack
+# Sphinx Stack
 
-*A pre-configured repository to build and publish documentation with Sphinx.*
+[![Sphinx Stack test](https://github.com/canonical/sphinx-stack/actions/workflows/test-sphinx-stack.yml/badge.svg)](https://github.com/canonical/sphinx-stack/actions/workflows/test-sphinx-stack.yml)
 
-## Description
+A standard set of tools for building and publishing Sphinx documentation.
 
-The Documentation Starter Pack includes:
+The Sphinx Stack contains a set of CLI commands and a default set of extensions,
+configuration options, and tests.
 
-* A bundled [Sphinx] theme, configuration, and extensions
-* Support for both reStructuredText (reST) and MyST Markdown
-* Build checks for links, spelling, and inclusive language
-* Customisation support layered over a core configuration
+## Basic usage
 
-See the full documentation: https://canonical-starter-pack.readthedocs-hosted.com/
+To try out the Sphinx Stack, clone it locally and navigate to the `/docs` directory:
 
-## Structure
+```shell
+git clone git@github.com:canonical/sphinx-stack.git
+cd docs
+```
 
-This section outlines the structure of this repository, and some key files.
+Then, run the command
 
-### `docs/`
+```shell
+make run
+```
 
-This directory contains the documentation for the Starter Pack itself.
+This will create a Python virtual environment, install necessary dependencies, build the
+documentation, and serve it to http://127.0.0.1:8000.
 
-To view it in your browser, navigate to this directory and type `make run`.
+To learn more about how to install and configure the Sphinx Stack for your own project,
+see the [Set up a new
+project](https://canonical-sphinx-stack.readthedocs-hosted.com/stable/tutorial/set-up/)
+guide in the official documentation.
 
-### `.github/workflows/`
+## Requirements and limitations
 
-This directory contains files used for documentation build checks via GitHub's CI.
+The Sphinx Stack is designed for projects hosted on GitHub. This is necessary to run the
+automatic checks in .github/workflows, and to publish your documentation on Read the
+Docs.
 
-The file `test-starter-pack.yml` tests the functionality of the Starter Pack project.
+If you have a project that is hosted on a different versioning platform, like Launchpad,
+[reach out to us](#reach-out).
 
-## Contributing
+## Community and support
 
-We welcome contributions to this project! If you have suggestions, bug fixes, or improvements, please open an issue or submit a pull request.
+The Sphinx Stack is an open-source project that warmly welcomes community involvement.
 
-Please read and sign our [Contributor Licence Agreement (CLA)] before submitting any changes. The agreement grants Canonical permission to use your contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs).
+If you’re new to the community, make sure to read through the [Ubuntu Code of
+Conduct](https://ubuntu.com/community/code-of-conduct) first.
 
-<!--Links-->
+### Reach out
 
-[Sphinx]: https://www.sphinx-doc.org/
-[Contributor Licence Agreement (CLA)]: https://ubuntu.com/legal/contributors
+* Report an issue or make a suggestion via
+  [GitHub](https://github.com/canonical/sphinx-stack/issues)
+* Come chat with the Canonical Documentation team in our [public Matrix
+  channel](https://matrix.to/#/#documentation:ubuntu.com)
+
+### Contribute
+
+The Sphinx Stack provides a shared foundation for Sphinx documentation projects, and
+contributions help improve the documentation of all its users.
+
+* See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on contributing to
+  development or documentation.
+* Check [open issues](https://github.com/canonical/sphinx-stack/issues)

docs/_dev/update_sp.py

@@ -1,28 +1,29 @@
 #! /usr/bin/env python
 
-# Initial update script for the starter pack.
+# Initial update script for the Sphinx Stack.
 #
 # Requires some manual intervention, but makes identifying updates and differences easier.
 #
 # For debugging, please run this script with DEBUGGING=1
-# e.g. user@device:~/git/Canonical/sphinx-docs-starter-pack/docs$ DEBUGGING=1 python _dev/update_sp.py
+# e.g. user@device:~/git/Canonical/sphinx-stack/docs$ DEBUGGING=1 python .sphinx/update_sp.py
 
 
 import glob
 import logging
 import os
-import requests
 import re
 import subprocess
 import sys
-from requests.exceptions import RequestException
+
+import requests
 from packaging.version import parse as parse_version
+from requests.exceptions import RequestException
 
 SPHINX_DIR = os.path.abspath(os.path.dirname(__file__))
-DOCS_DIR = os.path.abspath(os.path.join(SPHINX_DIR, '..'))
+DOCS_DIR = os.path.abspath(os.path.join(SPHINX_DIR, ".."))
 REQUIREMENTS = os.path.join(DOCS_DIR, "requirements.txt")
 SPHINX_UPDATE_DIR = os.path.join(SPHINX_DIR, "update")
-GITHUB_REPO = "canonical/sphinx-docs-starter-pack"
+GITHUB_REPO = "canonical/sphinx-stack"
 GITHUB_API_BASE = f"https://api.github.com/repos/{GITHUB_REPO}"
 GITHUB_API_DEV_DIR = f"{GITHUB_API_BASE}/contents/docs/_dev"
 GITHUB_RAW_BASE = f"https://raw.githubusercontent.com/{GITHUB_REPO}/main"
@@ -43,7 +44,7 @@ def main():
     except FileNotFoundError:
         print("WARNING\nWARNING\nWARNING")
         print(
-            "You need to update to at least version 1.0.0 of the starter pack to start using the update function."
+            "You need to update to at least version 1.0.0 of the Sphinx Stack to start using the update function."
         )
         print("You may experience issues using this functionality.")
         logging.debug("No local version found. Setting version to None")
@@ -61,7 +62,7 @@ def main():
     logging.debug("Comparing versions")
     if parse_version(local_version) < parse_version(latest_release):
         logging.debug("Local version is older than the release version.")
-        print("Starter pack is out of date.\n")
+        print("Sphinx Stack is out of date.\n")
 
         # Identify and download '_dev' dir files to '_dev/update'
         files_updated, new_files = update_static_files()
@@ -130,7 +131,7 @@ def main():
     except FileNotFoundError:
         print("requirements.txt not found")
         print(
-            "The updated starter pack has moved requirements.txt out of the '_dev' dir"
+            "The updated Sphinx Stack has moved requirements.txt out of the '_dev' dir"
         )
         print("requirements.txt not checked, please update your requirements manually")
 
@@ -142,7 +143,7 @@ def update_static_files():
 
     for item in query_api(GITHUB_API_DEV_DIR).json():
         logging.debug(f"Checking {item['name']}")
-        # Checks existing files in '_dev' starter pack static root for changed SHA
+        # Checks existing files in '_dev' Sphinx Stack static root for changed SHA
         if item["name"] in files and item["type"] == "file":
             index = files.index(item["name"])
             if item["sha"] != get_git_revision_hash(paths[index]):
@@ -162,9 +163,7 @@ def update_static_files():
         # Checks nested files '_dev/**/**.*' for changed SHA (single level of depth)
         elif item["type"] == "dir":
             logging.debug(item["name"] + " is a directory")
-            for nested_item in query_api(
-                f"{GITHUB_API_DEV_DIR}/{item['name']}"
-            ).json():
+            for nested_item in query_api(f"{GITHUB_API_DEV_DIR}/{item['name']}").json():
                 logging.debug(f"Checking {nested_item['name']}")
                 if nested_item["name"] in files:
                     index = files.index(nested_item["name"])
@@ -189,7 +188,7 @@ def update_static_files():
                                 SPHINX_UPDATE_DIR, item["name"], nested_item["name"]
                             ),
                         )
-        # Downloads NEW files in '_dev' starter pack static root
+        # Downloads NEW files in '_dev' Sphinx Stack static root
         else:
             if item["type"] == "file":
                 logging.debug(f"No local version found of {item['name']}")

docs/_dev/version

@@ -1 +1 @@
-1.6
+2.0