Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/how-to/configure-your-project.rst
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,7 @@ To add new extensions needed for your documentation set, add them to the ``exten

If any additional extensions need specific Python packages, ensure they are installed alongside the other requirements by adding them to the ``docs/requirements.txt`` file.

The Sphinx Stack fully supports only the third-party extensions included in the Starter pack. Support is limited for extensions you add or customize in requirements.txt

Add page-specific configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
21 changes: 11 additions & 10 deletions docs/how-to/update-sphinx-stack/legacy-sphinx-stack.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

.. _update-legacy-sphinx-stack:

Update the legacy Sphinx Stack
Update the legacy Sphinx Stack
==============================

This guide outlines the steps required to migrate a documentation project from the
Expand Down Expand Up @@ -65,7 +65,7 @@ Set up a new project
- ``.github/workflows/*``
#. Ensure the following files are moved to their original paths in the project. These
files are defaulted to the repository root, but may have be changed upon project
needs:
needs:

- ``.gitignore``
- ``.readthedocs.yml``
Expand Down Expand Up @@ -98,7 +98,7 @@ files, summarised in the following table:
:header-rows: 1

* - Configuration file
- Pre-extension
- Pre-extension
- Extension-based
* - ``conf.py``
- Common configurations shared by all Sphinx Stack projects
Expand All @@ -114,7 +114,7 @@ defaults are set for general configuration by inclusion of the ``canonical-sphin
extension.

Ensure that all the previous changes in the original ``custom_conf.py`` file are copied
to the new ``conf.py`` file.
to the new ``conf.py`` file.


Dependencies
Expand All @@ -123,15 +123,16 @@ Dependencies
If your project requires additional extensions beyond the default list, add the
extension list to the new project in ``docs/requirements.txt``.

The legacy Sphinx Stack fully supports only the third-party extensions included in the Starter pack. Support is limited for extensions you add or customize in requirements.txt

Documentation source files
~~~~~~~~~~~~~~~~~~~~~~~~~~

#. Copy all documentation source files from your original project to the new project,
keeping their original structure. These file may include but are not limited to:

- ``.md``
- ``.rst``
- ``.md``
- ``.rst``
- ``.txt``
- ``.json``
- images
Expand All @@ -158,7 +159,7 @@ These resources are bundled with the extension and are no longer provided as sou
files in the new Sphinx Stack.

If you have customised any of these resources in the original project, you need to
manually migrate these changes to the new project.
manually migrate these changes to the new project.

For example, if you added customised styling in the original
``.sphinx/_static/custom.css`` file, follow the steps:
Expand Down Expand Up @@ -235,9 +236,9 @@ following list illustrates the changes in the directory structure after the migr
│ ├── pa11y-ci.json # renamed to `pa11y.json`
│ └── spellingcheck.yaml
├── metrics # removed
│ └── scripts
│ ├── build_metrics.sh
│ └── source_metrics.sh
│ └── scripts
│ ├── build_metrics.sh
│ └── source_metrics.sh
├── reuse # removed
│ └── links.txt
├── .custom_wordlist.txt # moved to `docs/.custom_wordlist.txt`
Expand Down
Loading