diff --git a/README.md b/README.md index 6a801ef..3625aac 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,16 @@ -# Sphinx Stack +# Sphinx Stack testing -[![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) +An internal repository for various testing/QA experiments and benchmarks for [Sphinx Stack](https://github.com/canonical/sphinx-stack) functionality. Unrelated to the [standard documentation build tests](https://github.com/canonical/sphinx-stack/blob/main/.github/workflows/test-sphinx-stack.yml). -A standard set of tools for building and publishing Sphinx documentation. +This is kept in a separate repo to not interfere with the default Sphinx Stack template, and because I'm not exactly sure what all of this even is yet but I needed somewhere to put it. -The Sphinx Stack contains a set of CLI commands and a default set of extensions, -configuration options, and tests. +## Repository structure -## Basic usage +The **`main`** branch is a copy of the Sphinx Stack with the addition of a general canary page that renders example structures of all (relevant) default extensions of the Sphinx Stack. It's a work in progress, and currently relies on visual verification. -To try out the Sphinx Stack, clone it locally and navigate to the `/docs` directory: - -```shell -git clone git@github.com:canonical/sphinx-stack.git -cd docs -``` - -Then, run the command - -```shell -make run -``` - -This will create a Python virtual environment, install necessary dependencies, build the -documentation, and serve it to http://127.0.0.1:8000. - -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/latest/set-up-a-new-project/) -guide in the official documentation. - -## Requirements and limitations - -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. - -If you have a project that is hosted on a different versioning platform, like Launchpad, -[reach out to us](#reach-out). - -## Community and support - -The Sphinx Stack is an open-source project that warmly welcomes community involvement. - -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. - -### Reach out - -* 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) +Branches with the prefix **`scenario/`** will be simulations of documentation projects with different types of complexity. These don't exist yet, but plans include scenarios like: +* `scenario/custom-html-css` +* `scenario/custom-ci` +* `scenario/custom-requirements` +* `scenario/java` +* `scenario/custom-build` diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html index e1d1088..ffd301d 100644 --- a/docs/_templates/footer.html +++ b/docs/_templates/footer.html @@ -80,7 +80,7 @@ {%- endif %}
- {% if has_contributor_listing and display_contributors and pagename and page_source_suffix %} + {% if display_contributors and pagename and page_source_suffix %} {% set contributors = get_contributors_for_file(pagename, page_source_suffix) %} {% if contributors %} {% if contributors | length > 1 %} diff --git a/docs/canary-page.md b/docs/canary-page.md new file mode 100644 index 0000000..33f8056 --- /dev/null +++ b/docs/canary-page.md @@ -0,0 +1,694 @@ +--- +relatedlinks: "[Example link](https://example.com)" +hide-toc: true +--- + +# Test page for default extensions + +This page contains basic example structures from every MyST and rST extension that is included in the Sphinx Stack by default. + +## `canonical_sphinx` + +Below are the default extensions bundled into `canonical_sphinx`. + +### Furo theme + +This is partially tested by setting Furo's `hide-toc` feature to `true` in this page's metadata. + +**Expectation**: The right side of the page should **not** contain a table of contents. + +**HTML check**: The HTML of this page does **not** contain the following `
` classes: + +```html +
+ (...) +
+ (...) +``` + +### MyST parser + +This is tested with the `{sub-ref}` MyST directive to count words through `wordcount-words`. + +**Expectation**: There is a number in the sentence "This page has {sub-ref}`wordcount-words` words". + +### linkify-it-py + +This is tested by writing a URL in plain text and checking that it turns into a link. + +**Expectation**: //localhost is a clickable link. + +**HTML check**: + +```html +//localhost +``` + +## `notfound.extension` + +This is tested by accessing a non-existent sub-page of this documentation set. + +**Expectation**: https://documentation.ubuntu.com/sphinx-stack/a renders a "Page not found" message with the same CSS styling as the rest of the documentation, maintaining the left-side navigation and upper menu. + +## `sphinx_design` + +This is tested by rendering sample structures based on [`sphinx-design` documentation examples](https://sphinx-design.readthedocs.io/en/latest/index.html). + +### Grids + +#### Basic grid + +**Expectation**: The following grids have an outer outline and three grid items. + +````{grid} +:outline: + +```{grid-item} +MyST grid item 1 +``` +```{grid-item} +MyST grid item 2 +``` +```{grid-item} +MyST grid item 3 +``` +```` + +```{eval-rst} +.. grid:: + :outline: + + .. grid-item:: + reST grid item 1 + + .. grid-item:: + reST grid item 2 + + .. grid-item:: + reST grid item 3 +``` + +**HTML check**: + +```html +
+ (...) +``` + +#### Card grids + +**Expectation**: The following grids are composed of cards. + +````{grid} +```{grid-item-card} Title 1 +MyST grid item card 1 +``` +```{grid-item-card} Title 2 +MyST grid item card 2 +``` +```{grid-item-card} Title 3 +MyST grid item card 3 +``` +```` + +```{eval-rst} +.. grid:: + + .. grid-item-card:: Title 1 + + reST grid item card 1 + + .. grid-item-card:: Title 2 + + reST grid item card 2 + + .. grid-item-card:: Title 3 + + reST grid item card 3 +``` + +**HTML check**: + +```html +
+ (...) +``` + +### Cards + +#### Basic card + +```{card} MyST card title +Card content +``` + +```{eval-rst} +.. card:: reST card title + + Card content +``` + +**HTML check**: + +```html +
+ (...) +``` + +#### Card with header and footer + +**Expectation**: The following cards have header and footer text. + +```{card} MyST card title +Header +^^^ +Card content ++++ +Footer +``` + +```{eval-rst} +.. card:: reST card title + + Header + ^^^ + Card content + +++ + Footer +``` + +**HTML check**: + +```html +
+ (...) +