# sphinxcontrib-relativeinclude
[](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/actions/workflows/publish.yml)
[](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/actions/workflows/docs.yml)
[](https://pypi.org/project/sphinxcontrib-relativeinclude)
[](https://pypi.org/project/sphinxcontrib-relativeinclude)
[](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/blob/main/LICENSE.txt)
## About
This package implements a new reST directive to include files and translate paths included in those files.
## Installation
The project is hosted on [PyPI](https://pypi.org/project/sphinxcontrib-relativeinclude), and can be installed via `pip`.
```console
pip install sphinxcontrib-relativeinclude
```
You can find the contents of the README and the module documentation for the latest release [online](https://fynnfreyer.github.io/sphinxcontrib-relativeinclude).
It's also available [PDF](https://fynnfreyer.github.io/sphinxcontrib-relativeinclude/files/sphinxcontrib-relativeinclude.pdf) or [EPUB](https://fynnfreyer.github.io/sphinxcontrib-relativeinclude/files/sphinxcontrib-relativeinclude.epub).
## Motivation
Let's assume you want to transclude the `README.rst` sitting in your repository root, in your `docs/index.rst`, so it automatically shows up in your generated documentation.
You can just use reST's standard [`include`](https://docutils.sourceforge.io/docs/ref/rst/directives.html#include) directive.
```rst
.. include: ../README.rst
```
**Sidenote:** If you're using a parser, like [MyST](https://myst-parser.readthedocs.io/en/stable/), you could also easily include markdown files, of course.
This will insert the contents of your README in the appropriate place, and even take care of heading levels for you.
The problem arises when you have images or other files included in there. Sphinx won't resolve those links properly, i.e., relative to the README, but instead relative to your Sphinx index document.
That means those pictures won't show up, which, needless to say, is not optimal.
If you use your valuable time to create visual resources for your documentation these should also be included in the documentation output.
|  |
|:----------------------------------------------------------------------------------------------------------------------------------------:|
| Picture of a honey badger by [Sumeetmoghe on Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Honey_Badger.jpg) (CC-BY-SA-4.0) |
This picture uses a relative path to a file in the [`docs/assets`](docs/assets) directory, and would happily show up in your Git repo, but not in your documentation.
This is what this extension is supposed to solve.
It defines a new `relativeinclude` directive, that takes relative paths in included files, and resolves them into absolute ones.
This way your images show up in your documentation output, but you don't have to hardcode absolute paths in your documentation.
(Cf. this awesome honey badger [here](https://fynnfreyer.github.io/sphinxcontrib-relativeinclude/#motivation))
**Caveat emptor:** At this point in time, nested includes are unfortunately not supported.
(See [TODOs](#todos))
## Usage
You have to enable the extension in your `conf.py` file.
```python
# in conf.py
extensions = [
# ...
"sphinxcontrib.relativeinclude",
# ...
]
```
After that, the directive will be available for you to use in your documentation.
```rst
.. relativeinclude: ../README.md
:parser: myst_parser.docutils_
```
It supports the same options as the standard [`include`](https://docutils.sourceforge.io/docs/ref/rst/directives.html#include) directive.
If not, you've found a bug, and I'd be happy if you reported it on the [issue tracker](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/issues).
Please provide thorough description, and a minimal reproducible example, i.e., (abbreviated) reST files you used, potentially your `conf.py` contents and maybe other relevant info.
If you want to see some real code, check out this repository's documentation at [`docs/index.rst`](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/blob/main/docs/index.rst).
## TODOs
- support multiple levels of indirection
- properly register directive on install
## License
`sphinxcontrib-relativeinclude` is distributed under the terms of the [MIT](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/blob/main/LICENSE.txt) license.
Raw data
{
"_id": null,
"home_page": "",
"name": "sphinxcontrib-relativeinclude",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "docutils,reST,restructured text,sphinx",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/48/6d/9e70971a55cf22de432c3cfe2f22b97df1f405a208e6500611807a42fd53/sphinxcontrib_relativeinclude-0.0.5.tar.gz",
"platform": null,
"description": "# sphinxcontrib-relativeinclude\n\n[](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/actions/workflows/publish.yml)\n[](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/actions/workflows/docs.yml)\n[](https://pypi.org/project/sphinxcontrib-relativeinclude)\n[](https://pypi.org/project/sphinxcontrib-relativeinclude)\n[](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/blob/main/LICENSE.txt)\n\n## About\n\nThis package implements a new reST directive to include files and translate paths included in those files.\n\n## Installation\n\nThe project is hosted on [PyPI](https://pypi.org/project/sphinxcontrib-relativeinclude), and can be installed via `pip`.\n\n```console\npip install sphinxcontrib-relativeinclude\n```\n\nYou can find the contents of the README and the module documentation for the latest release [online](https://fynnfreyer.github.io/sphinxcontrib-relativeinclude).\nIt's also available [PDF](https://fynnfreyer.github.io/sphinxcontrib-relativeinclude/files/sphinxcontrib-relativeinclude.pdf) or [EPUB](https://fynnfreyer.github.io/sphinxcontrib-relativeinclude/files/sphinxcontrib-relativeinclude.epub).\n\n## Motivation\n\nLet's assume you want to transclude the `README.rst` sitting in your repository root, in your `docs/index.rst`, so it automatically shows up in your generated documentation.\nYou can just use reST's standard [`include`](https://docutils.sourceforge.io/docs/ref/rst/directives.html#include) directive.\n\n```rst\n.. include: ../README.rst\n```\n\n**Sidenote:** If you're using a parser, like [MyST](https://myst-parser.readthedocs.io/en/stable/), you could also easily include markdown files, of course.\n\nThis will insert the contents of your README in the appropriate place, and even take care of heading levels for you.\n\nThe problem arises when you have images or other files included in there. Sphinx won't resolve those links properly, i.e., relative to the README, but instead relative to your Sphinx index document.\nThat means those pictures won't show up, which, needless to say, is not optimal.\nIf you use your valuable time to create visual resources for your documentation these should also be included in the documentation output.\n\n|  |\n|:----------------------------------------------------------------------------------------------------------------------------------------:|\n| Picture of a honey badger by [Sumeetmoghe on Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Honey_Badger.jpg) (CC-BY-SA-4.0) |\n\nThis picture uses a relative path to a file in the [`docs/assets`](docs/assets) directory, and would happily show up in your Git repo, but not in your documentation.\n\nThis is what this extension is supposed to solve.\nIt defines a new `relativeinclude` directive, that takes relative paths in included files, and resolves them into absolute ones.\nThis way your images show up in your documentation output, but you don't have to hardcode absolute paths in your documentation.\n(Cf. this awesome honey badger [here](https://fynnfreyer.github.io/sphinxcontrib-relativeinclude/#motivation))\n\n**Caveat emptor:** At this point in time, nested includes are unfortunately not supported.\n(See [TODOs](#todos))\n\n## Usage\n\nYou have to enable the extension in your `conf.py` file.\n\n```python\n# in conf.py\nextensions = [\n # ...\n \"sphinxcontrib.relativeinclude\",\n # ...\n]\n```\n\nAfter that, the directive will be available for you to use in your documentation.\n\n```rst\n.. relativeinclude: ../README.md\n :parser: myst_parser.docutils_\n```\n\nIt supports the same options as the standard [`include`](https://docutils.sourceforge.io/docs/ref/rst/directives.html#include) directive.\nIf not, you've found a bug, and I'd be happy if you reported it on the [issue tracker](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/issues).\nPlease provide thorough description, and a minimal reproducible example, i.e., (abbreviated) reST files you used, potentially your `conf.py` contents and maybe other relevant info.\n\nIf you want to see some real code, check out this repository's documentation at [`docs/index.rst`](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/blob/main/docs/index.rst).\n\n## TODOs\n\n- support multiple levels of indirection\n- properly register directive on install\n\n## License\n\n`sphinxcontrib-relativeinclude` is distributed under the terms of the [MIT](https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/blob/main/LICENSE.txt) license.\n",
"bugtrack_url": null,
"license": "",
"summary": "Implements a new reST include directive to translate relative paths.",
"version": "0.0.5",
"project_urls": {
"Documentation": "https://fynnfreyer.github.io/sphinxcontrib-relativeinclude",
"Issues": "https://github.com/FynnFreyer/sphinxcontrib-relativeinclude/issues",
"Source": "https://github.com/FynnFreyer/sphinxcontrib-relativeinclude"
},
"split_keywords": [
"docutils",
"rest",
"restructured text",
"sphinx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e7a95b4956d44f197cf44aecb3e10de6a5b0beb0009212d0bbb614f6768bca15",
"md5": "979e7cdd73850ad95783f81a8ead759d",
"sha256": "43df4bf253720a0bf731eb1aaa1b7a738d280f76bda75acd5564d6eafe04c59f"
},
"downloads": -1,
"filename": "sphinxcontrib_relativeinclude-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "979e7cdd73850ad95783f81a8ead759d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6932,
"upload_time": "2023-12-03T17:42:02",
"upload_time_iso_8601": "2023-12-03T17:42:02.577230Z",
"url": "https://files.pythonhosted.org/packages/e7/a9/5b4956d44f197cf44aecb3e10de6a5b0beb0009212d0bbb614f6768bca15/sphinxcontrib_relativeinclude-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "486d9e70971a55cf22de432c3cfe2f22b97df1f405a208e6500611807a42fd53",
"md5": "e9004b328ad9e4addeac9f441dbc1326",
"sha256": "c595e2c6ca285fea967539e4eb5b251ff132a6ccf2ba19077edc8c27de930b1e"
},
"downloads": -1,
"filename": "sphinxcontrib_relativeinclude-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "e9004b328ad9e4addeac9f441dbc1326",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7766,
"upload_time": "2023-12-03T17:42:04",
"upload_time_iso_8601": "2023-12-03T17:42:04.314745Z",
"url": "https://files.pythonhosted.org/packages/48/6d/9e70971a55cf22de432c3cfe2f22b97df1f405a208e6500611807a42fd53/sphinxcontrib_relativeinclude-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-03 17:42:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FynnFreyer",
"github_project": "sphinxcontrib-relativeinclude",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinxcontrib-relativeinclude"
}
JSON
