# sphinx_versioning
A Sphinx extension to manage versioned documentation.
## Overview
`sphinx-versioning` is a Sphinx extension that manages versioned documentation, allowing users to maintain multiple versions of their documentation with ease. This plugin makes it simple to create, view, and navigate between different versions, providing an enhanced user experience.
### Features
- **Version Creation**: Easily create new versions of your documentation using the command-line interface.
- **Version Deletion**: Manage your existing versions, including the ability to delete obsolete ones.
- **Version Navigation**: Conveniently navigate between different versions through a drop-down menu.
- **Virtual Environment Support**: Virtual Environment Support: Optionally use a virtual environment when building a new version, ensuring that documentation is built with a consistent set of dependencies and avoid.
## Installation
```sh
pip install sphinx-versioning
```
## Usage
### Configuration in Sphinx
1. In your Sphinx project's `conf.py` file, add 'sphinx_versioning' to the extensions list:
```python
extensions = [
...
'sphinx_versioning',
...
]
```
2. Update your `conf.py` file to include the `sphinx_versioning.html` template in the `html_sidebars` configuration:
```python
html_sidebars = {
'**': [
# ... other sidebars ...
# Suggest putting the extension above the search bar for better UX.
'sidebar/sphinx_versioning.html',
]
}
```
3. If you haven't set it already, set `html_static_path` as follows:
```python
html_static_path = ['_static']
```
### Command Line Interface
The `sphinx-version` command-line tool provides functionality to manage versions:
#### Create a New Version based on the current source files:
```sh
sphinx-version VERSION_NAME
```
Where `VERSION_NAME` is a user-defined name for the documentation version (e.g., 'v1.0').
#### Create a New Version using a Virtual Environment:
To create a new version using a virtual environment and install dependencies from specific requirements files:
```sh
sphinx-version VERSION_NAME --venv --requirements req1.txt,req2.txt
```
> **Note**: The `--requirements` flag expects the requirements file names. These files should be located in the same directory as the Sphinx documentation. The `--requirements` flag should always be used with the `--venv` flag.
> **Why use a virtual environment?**: Using a virtual environment ensures that each version of your documentation is built with a consistent set of dependencies. This can help avoid unexpected changes or issues that might arise if Sphinx or its extensions/themes update over time.
#### Delete an Existing Version:
```sh
sphinx-version VERSION_NAME -d
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Yihengxiong6/sphinx_versioning",
"name": "sphinx-versioning",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "sphinx documentation versioning",
"author": "Yiheng Xiong",
"author_email": "georgex8866@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c6/48/3820aba4dd919ffbbeef9ff81a987b3826d75031282e2f730901138cc583/sphinx-versioning-0.1.5.tar.gz",
"platform": null,
"description": "# sphinx_versioning\nA Sphinx extension to manage versioned documentation.\n\n## Overview\n\n`sphinx-versioning` is a Sphinx extension that manages versioned documentation, allowing users to maintain multiple versions of their documentation with ease. This plugin makes it simple to create, view, and navigate between different versions, providing an enhanced user experience.\n\n### Features\n\n- **Version Creation**: Easily create new versions of your documentation using the command-line interface.\n\n- **Version Deletion**: Manage your existing versions, including the ability to delete obsolete ones.\n\n- **Version Navigation**: Conveniently navigate between different versions through a drop-down menu.\n\n- **Virtual Environment Support**: Virtual Environment Support: Optionally use a virtual environment when building a new version, ensuring that documentation is built with a consistent set of dependencies and avoid. \n\n## Installation\n\n```sh\npip install sphinx-versioning\n```\n\n## Usage\n\n### Configuration in Sphinx\n\n1. In your Sphinx project's `conf.py` file, add 'sphinx_versioning' to the extensions list:\n\n```python\nextensions = [\n ...\n 'sphinx_versioning',\n ...\n]\n```\n\n2. Update your `conf.py` file to include the `sphinx_versioning.html` template in the `html_sidebars` configuration:\n\n```python\nhtml_sidebars = {\n '**': [\n # ... other sidebars ...\n # Suggest putting the extension above the search bar for better UX.\n 'sidebar/sphinx_versioning.html',\n ]\n}\n```\n\n3. If you haven't set it already, set `html_static_path` as follows:\n\n```python\nhtml_static_path = ['_static']\n```\n\n### Command Line Interface\n\nThe `sphinx-version` command-line tool provides functionality to manage versions:\n\n#### Create a New Version based on the current source files:\n\n```sh\nsphinx-version VERSION_NAME\n```\nWhere `VERSION_NAME` is a user-defined name for the documentation version (e.g., 'v1.0').\n\n#### Create a New Version using a Virtual Environment:\n\nTo create a new version using a virtual environment and install dependencies from specific requirements files:\n\n```sh\nsphinx-version VERSION_NAME --venv --requirements req1.txt,req2.txt\n```\n\n> **Note**: The `--requirements` flag expects the requirements file names. These files should be located in the same directory as the Sphinx documentation. The `--requirements` flag should always be used with the `--venv` flag.\n\n\n> **Why use a virtual environment?**: Using a virtual environment ensures that each version of your documentation is built with a consistent set of dependencies. This can help avoid unexpected changes or issues that might arise if Sphinx or its extensions/themes update over time.\n\n#### Delete an Existing Version:\n\n```sh\nsphinx-version VERSION_NAME -d\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Sphinx extension to manage versioned documentation",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/Yihengxiong6/sphinx_versioning"
},
"split_keywords": [
"sphinx",
"documentation",
"versioning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "479961f321f7e1dc46ecadc00e83a4f8e706957d7a3484556eac781bfd85c7ac",
"md5": "2d6c727696bb8004f2743ff43988a267",
"sha256": "40cf15d00ab41ae8b38340d4835b326170e3e728143d9fae6f9af263965e22be"
},
"downloads": -1,
"filename": "sphinx_versioning-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d6c727696bb8004f2743ff43988a267",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7405,
"upload_time": "2023-12-13T19:15:06",
"upload_time_iso_8601": "2023-12-13T19:15:06.307135Z",
"url": "https://files.pythonhosted.org/packages/47/99/61f321f7e1dc46ecadc00e83a4f8e706957d7a3484556eac781bfd85c7ac/sphinx_versioning-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c6483820aba4dd919ffbbeef9ff81a987b3826d75031282e2f730901138cc583",
"md5": "3fdc83c55941a5a5a2a7f22d8857269b",
"sha256": "40f3cd0f282cd0ad08f96650ef0caf228c4a001c72b59a0b0eca95024a3d7bc8"
},
"downloads": -1,
"filename": "sphinx-versioning-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "3fdc83c55941a5a5a2a7f22d8857269b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7552,
"upload_time": "2023-12-13T19:15:08",
"upload_time_iso_8601": "2023-12-13T19:15:08.179924Z",
"url": "https://files.pythonhosted.org/packages/c6/48/3820aba4dd919ffbbeef9ff81a987b3826d75031282e2f730901138cc583/sphinx-versioning-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-13 19:15:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Yihengxiong6",
"github_project": "sphinx_versioning",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sphinx-versioning"
}
JSON
