<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
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:
```shell script
./site.sh build-site && ./site.sh prepare-theme
```
3. To install the required Python packages, in `<ROOT DIRECTORY>/sphinx_airflow_theme` run:
```shell script
pip install -e .
```
4. To launch the demo documentation page, in `<ROOT DIRECTORY>/sphinx_airflow_theme/demo` run:
```shell script
./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:
```shell script
./site.sh build-site
```
2. Package the Sphinx theme in a `whl` file:
```shell script
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:
```shell script
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:
```shell script
cp ./sphinx_airflow_theme-0.0.11-py3-none-any.whl ${AIRFLOW_REPO}/files/
```
5. In `airflow` repository, initiate a new breeze environment:
```shell script
breeze
```
6. In the breeze container, generate the documentation after installing the theme:
```shell script
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:
```shell script
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:**
```python
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:**
```python
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** `<ROOT DIRECTORY>/landing-pages/src/docs-index.js
Raw data
{
"_id": null,
"home_page": "https://github.com/apache/airflow-site/tree/aip-11",
"name": "sphinx-airflow-theme",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Apache Software Foundation",
"author_email": "dev@airflow.apache.org",
"download_url": "https://files.pythonhosted.org/packages/5a/9e/984a8dda20807170cae5779ae702eba80466a5bd54c3ac47672783c92080/sphinx_airflow_theme-0.0.12.tar.gz",
"platform": null,
"description": "<!--\n Licensed to the Apache Software Foundation (ASF) under one\n or more contributor license agreements. See the NOTICE file\n distributed with this work for additional information\n regarding copyright ownership. The ASF licenses this file\n to you under the Apache License, Version 2.0 (the\n \"License\"); you may not use this file except in compliance\n with the License. You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing,\n software distributed under the License is distributed on an\n \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n KIND, either express or implied. See the License for the\n specific language governing permissions and limitations\n under the License.\n-->\n\nSphinx theme for Airflow\n========================\n\nSphinx theme for Apache Airflow documentation.\n\n# Install from sources\n\nIn order to start working with the theme, please follow the instructions below.\n\n1. Make sure your `python` shell command executes Python3 interpreter. If necessary, use a virtual environment:\n ```\n mkvirtualenv -p python3 <name_of_environment>\n ```\n\n2. To make Javascript and CSS code available for the theme, run the following command in the root directory:\n ```shell script\n ./site.sh build-site && ./site.sh prepare-theme\n ```\n\n3. To install the required Python packages, in `<ROOT DIRECTORY>/sphinx_airflow_theme` run:\n ```shell script\n pip install -e .\n ```\n\n4. To launch the demo documentation page, in `<ROOT DIRECTORY>/sphinx_airflow_theme/demo` run:\n ```shell script\n ./docs.sh build && ./docs.sh preview\n ```\n\n# Generate Airflow documentation with Sphinx theme changes\n\nIf you made some modifications to Sphinx theme and want to generate Airflow documentation to check the end results,\nplease follow these steps:\n\n1. In `airflow-site` repository, build Airflow website:\n ```shell script\n ./site.sh build-site\n ```\n\n2. Package the Sphinx theme in a `whl` file:\n ```shell script\n cd ./sphinx_airflow_theme\n python3 setup.py sdist bdist_wheel\n ```\n\n3. (Optional) Double-check your modifications to the Sphinx theme are in the `whl` file:\n ```shell script\n pip install wheel\n wheel unpack ./sphinx_airflow_theme-0.0.11-py3-none-any.whl\n ```\n\n4. Copy the `whl` file to `files` directory in `airflow` repository:\n ```shell script\n cp ./sphinx_airflow_theme-0.0.11-py3-none-any.whl ${AIRFLOW_REPO}/files/\n ```\n\n5. In `airflow` repository, initiate a new breeze environment:\n ```shell script\n breeze\n ```\n\n6. In the breeze container, generate the documentation after installing the theme:\n ```shell script\n pip install /files/sphinx_airflow_theme-0.0.11-py3-none-any.whl --force-reinstall\n # Generate Airflow documentation only. If you need to generate the whole documentation (all providers),\n # you can do it using `/opt/airflow/scripts/in_container/run_docs_build.sh`. It takes longer to execute.\n /opt/airflow/scripts/in_container/run_docs_build.sh --package-filter apache-airflow\n ```\n\n7. Verify the documentation generated is correct and includes your modifications. The documentation is generated in\n`docs/_build/docs/`. If you generated Airflow documentation only, you can check the results in\n`docs/_build/docs/apache-airflow/latest/`.\n\n\n\n# Install developer version\n\nTo install the latest development version of a theme, run:\n```shell script\nTHEME_VERSION=\"$(curl -s https://api.github.com/repos/apache/airflow-site/releases/latest | grep '\"tag_name\":' | cut -d '\"' -f 4)\"\npip install \"https://github.com/apache/airflow-site/releases/download/${THEME_VERSION}/sphinx_airflow_theme-${THEME_VERSION}-py3-none-any.whl\"\n```\nPython packages for your PRs is available as downloadable artifact in GitHub Actions after\nthe CI builds your PR.\n\n# Configuration\n\nA theme that supports the following configuration options under the `html_theme_options` dict in your projects `conf.py`:\n\n## `navbar_links`\n\nThe 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.\n\n**Example values:**\n```python\nhtml_theme_options = {\n 'navbar_links': [\n {'href': '/docs/', 'text': 'Documentation'}\n ]\n}\n```\n\n(This is the default)\n\n## `hide_website_buttons`\n\nIf ``True``, all links on the same domain but not pointing to this theme's page (e.g. `/community/`) will be hidden.\n\n**Example values:**\n```python\nhtml_theme_options = {\n 'hide_website_buttons': False,\n}\n```\n\n## `sidebar_collapse`\n## `sidebar_includehidden`\n\nControls the ToC display in the sidebar. See https://www.sphinx-doc.org/en/master/templating.html#toctree for more info\n\n# Theme's source files\n\n - `<ROOT DIRECTORY>/sphinx_airflow_theme/sphinx_airflow_theme` - HTML files\n - `<ROOT DIRECTORY>/landing-pages/site/assets/scss` - SCSS files\n - `<ROOT DIRECTORY>/landing-pages/src/js` - Javascript files. If you create a new JS file, **don't forget to include it\n in** `<ROOT DIRECTORY>/landing-pages/src/docs-index.js\n\n\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Airflow theme for Sphinx",
"version": "0.0.12",
"project_urls": {
"Homepage": "https://github.com/apache/airflow-site/tree/aip-11"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ff0a7fee15c8d703acb1ea54a3a05dacd861c30022285c8040eb6d9271d2a49e",
"md5": "3a778e0fcb47b266ec68da29dfca23a1",
"sha256": "41a2bcf3027d104d3e90306ae13759433a8423b7439976461096a4a10c37c325"
},
"downloads": -1,
"filename": "sphinx_airflow_theme-0.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a778e0fcb47b266ec68da29dfca23a1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 99847,
"upload_time": "2023-04-17T21:25:09",
"upload_time_iso_8601": "2023-04-17T21:25:09.659708Z",
"url": "https://files.pythonhosted.org/packages/ff/0a/7fee15c8d703acb1ea54a3a05dacd861c30022285c8040eb6d9271d2a49e/sphinx_airflow_theme-0.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5a9e984a8dda20807170cae5779ae702eba80466a5bd54c3ac47672783c92080",
"md5": "34ea81d820936a1916c99bb6f61945bc",
"sha256": "820490fd789fe8536a073131db865be5e74eb0f77f52b95b07b0eaa21684d3a1"
},
"downloads": -1,
"filename": "sphinx_airflow_theme-0.0.12.tar.gz",
"has_sig": false,
"md5_digest": "34ea81d820936a1916c99bb6f61945bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4556,
"upload_time": "2023-04-17T21:25:11",
"upload_time_iso_8601": "2023-04-17T21:25:11.879143Z",
"url": "https://files.pythonhosted.org/packages/5a/9e/984a8dda20807170cae5779ae702eba80466a5bd54c3ac47672783c92080/sphinx_airflow_theme-0.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-17 21:25:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "apache",
"github_project": "airflow-site",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-airflow-theme"
}
JSON
