Skip to main content

Airflow theme for Sphinx

Project description

Sphinx theme for Airflow

Sphinx theme for Apache Airflow documentation.

Install from sources

In order to start working with the theme, please follow the instructions below.

  1. Make sure your python shell command executes Python3 interpreter. If necessary, use a virtual environment:

    mkvirtualenv -p python3 <name_of_environment>
    
  2. To make Javascript and CSS code available for the theme, run the following command in the root directory:

    ./site.sh build-site && ./site.sh prepare-theme
    
  3. To install the required Python packages, in <ROOT DIRECTORY>/sphinx_airflow_theme run:

    pip install -e .
    
  4. To launch the demo documentation page, in <ROOT DIRECTORY>/sphinx_airflow_theme/demo run:

    ./docs.sh build && ./docs.sh preview
    

Generate Airflow documentation with Sphinx theme changes

If you made some modifications to Sphinx theme and want to generate Airflow documentation to check the end results, please follow these steps:

  1. In airflow-site repository, build Airflow website:

    ./site.sh build-site
    
  2. Package the Sphinx theme in a whl file:

    cd ./sphinx_airflow_theme
    python3 setup.py sdist bdist_wheel
    
  3. (Optional) Double-check your modifications to the Sphinx theme are in the whl file:

    pip install wheel
    wheel unpack ./sphinx_airflow_theme-0.0.11-py3-none-any.whl
    
  4. Copy the whl file to files directory in airflow repository:

    cp ./sphinx_airflow_theme-0.0.11-py3-none-any.whl ${AIRFLOW_REPO}/files/
    
  5. In airflow repository, initiate a new breeze environment:

    breeze
    
  6. In the breeze container, generate the documentation after installing the theme:

    pip install /files/sphinx_airflow_theme-0.0.11-py3-none-any.whl --force-reinstall
    # Generate Airflow documentation only. If you need to generate the whole documentation (all providers),
    # you can do it using `/opt/airflow/scripts/in_container/run_docs_build.sh`. It takes longer to execute.
    /opt/airflow/scripts/in_container/run_docs_build.sh --package-filter apache-airflow
    
  7. Verify the documentation generated is correct and includes your modifications. The documentation is generated in docs/_build/docs/. If you generated Airflow documentation only, you can check the results in docs/_build/docs/apache-airflow/latest/.

Install developer version

To install the latest development version of a theme, run:

THEME_VERSION="$(curl -s https://api.github.com/repos/apache/airflow-site/releases/latest | grep '"tag_name":' | cut -d '"' -f 4)"
pip install "https://github.com/apache/airflow-site/releases/download/${THEME_VERSION}/sphinx_airflow_theme-${THEME_VERSION}-py3-none-any.whl"

Python packages for your PRs is available as downloadable artifact in GitHub Actions after the CI builds your PR.

Configuration

A theme that supports the following configuration options under the html_theme_options dict in your projects conf.py:

navbar_links

The list of links that should be available in the navigation bar at the top of the pages. The order of items will not be changed.

Example values:

html_theme_options = {
    'navbar_links': [
        {'href': '/docs/', 'text': 'Documentation'}
    ]
}

(This is the default)

hide_website_buttons

If True, all links on the same domain but not pointing to this theme's page (e.g. /community/) will be hidden.

Example values:

html_theme_options = {
  'hide_website_buttons': False,
}

sidebar_collapse

sidebar_includehidden

Controls the ToC display in the sidebar. See https://www.sphinx-doc.org/en/master/templating.html#toctree for more info

Theme's source files

  • <ROOT DIRECTORY>/sphinx_airflow_theme/sphinx_airflow_theme - HTML files
  • <ROOT DIRECTORY>/landing-pages/site/assets/scss - SCSS files
  • <ROOT DIRECTORY>/landing-pages/src/js - Javascript files. If you create a new JS file, don't forget to include it in `/landing-pages/src/docs-index.js

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_airflow_theme-0.0.12.tar.gz (4.6 kB view details)

Uploaded Source

Built Distribution

sphinx_airflow_theme-0.0.12-py3-none-any.whl (99.8 kB view details)

Uploaded Python 3

File details

Details for the file sphinx_airflow_theme-0.0.12.tar.gz.

File metadata

  • Download URL: sphinx_airflow_theme-0.0.12.tar.gz
  • Upload date:
  • Size: 4.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.9.13

File hashes

Hashes for sphinx_airflow_theme-0.0.12.tar.gz
Algorithm Hash digest
SHA256 820490fd789fe8536a073131db865be5e74eb0f77f52b95b07b0eaa21684d3a1
MD5 34ea81d820936a1916c99bb6f61945bc
BLAKE2b-256 5a9e984a8dda20807170cae5779ae702eba80466a5bd54c3ac47672783c92080

See more details on using hashes here.

Provenance

File details

Details for the file sphinx_airflow_theme-0.0.12-py3-none-any.whl.

File metadata

File hashes

Hashes for sphinx_airflow_theme-0.0.12-py3-none-any.whl
Algorithm Hash digest
SHA256 41a2bcf3027d104d3e90306ae13759433a8423b7439976461096a4a10c37c325
MD5 3a778e0fcb47b266ec68da29dfca23a1
BLAKE2b-256 ff0a7fee15c8d703acb1ea54a3a05dacd861c30022285c8040eb6d9271d2a49e

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page