Updating package data¶
Changing existing data¶
To extend or manipulate the data for a specific extension or theme, please
add an entry to the file
.. needextend:: SUNPY-SPHINX-THEME :sphinx_type: theme :+tags: theme, sunpy
The above code is changing data of a need-element with the ID
It overwrites the
sphinx_type with the value
also extends the
tags attribute by a new value.
Changing or better extending data is a common task in the awesomesphinx projects. It’s mostly used to classify an extension or theme, to put it in specific categories for the user.
Adding new package¶
Normally all extensions and themes get imported automatically from PyPI if they have set the correct classifiers in their packages.
However, there are projects, which are not released on PyPI or haven’t set the right classifiers. Therefore these packages need to be registered in awesomesphinx by hand.
Register a package from PyPI¶
The best and most correct way of documenting a package here is to make sure it contains the correct classifiers. If this is the case, it will be found on the upcoming import run.
Each Python packaging tool does support setting classifiers. Please take a look at the related documentation to do so.
The used classifiers for filtering are defined inside
/projects.py file and are currently:
PROJECT_FILTERS = [ ['Framework :: Sphinx'], ['Framework :: Sphinx :: Extension'], ['Framework :: Sphinx :: Theme'] ]
Not matching classifiers¶
If a package does not match the classifiers, which are used to search for packages on PyPI, it can be added by hand. However, it still must be available on PyPI!
Please open the file
/projects.py and add the package-name to
EXTRA_PROJECTS = [ 'MY-NEW-PACKAGE' # <-- This is new 'sphinx-copybutton', 'doxysphinx' ]
Please be sure that the used name can be used to identify the package on PyPI, for instance by copying the name from the PyPI URL of the package.
Manually add a new package¶
Please open the related category file from the
needimport statement you are free to add a new Sphinx-Needs element, which represents
.. software:: My new theme :id: MY-NEW-theme :sphinx_type: theme :monthly: 0 :release_date: 2022-09-24T21:26:03 :release_name: 2.1.0 :code: https://github.com/me/package :pypi: https://PyPI.org/package :website: https://my-new-package.com
The values for
release_days get calculated automatically.
Please be aware that this is the worst way of adding a new extension/theme.
The values of
monthly are not accurate and would need to be
maintained by hand. It is much better to release the package on PyPI with the correct
Tags are defined inside
/projectspy, inside the variable
PROJECT_TAGS is a dictionary, where the key the is tag name and the value is an rst-based description, which
is taken for the documentation.
Each tag inside
PROJECT_TAGS gets reported automatically. No further actions are needed.
If a new tag is needed, simply add it to
PROJECT_TAGS, use it for at least one Sphinx element, and create a PR.
PyPI_json.py script is using Google BigQuery to get information about the download numbers of PyPI.
You need a google cloud account and an authentication-file to run these queries.
The installation guide of PyPInfo has a great chapter on how to get and configure a google cloud account.
The authentication-file must be set via ENV variable.
If you use our
.vscode/launch.json config, this is set automatically to
The AwesomeSphinx data workflow is as follows:
/scripts/PyPI_json.pygets executed (currently done manually).
Search for packages on PyPI by classifiers.
Requests package info from PyPI for each package.
Queries PyPI-BigQuery-data for download numbers of the last 30 days.
Stores all data in a
Extracts needed data only.
Constructs need-objects internally.
awesome.json, which contains the need-objects and is compliant with the Sphinx-Needs
Sphinx build gets started.
awesome.jsonis used to import need-object for specific categories.
Jinja templates get rendered and inject data.
Value calculation is done via the
dynamic functionsfeature of Sphinx-Needs.
Own Awesome X list¶
The used code and documentation configuration are not specific to Sphinx.
With 1-2 line changes in the file
/projects.py for the used classifiers filters, documentation projects can
be created for other Python-based projects.
It must be currently Python-based, as the
pypi_json.py script is using PyPI and BigQuery Table from PyPI to get needed data.
If this gets changed as well, also other tools can be documented as well.