| Name | literate-sphinx JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | A literate programming extension for Sphinx |
| upload_time | 2023-08-05 00:27:41 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | None |
| keywords |
sphinx
literate programming
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Literate Sphinx
Literate Sphinx is a [literate
programming](https://en.wikipedia.org/wiki/Literate_programming) extension for
[Sphinx](https://www.sphinx-doc.org/). Literate programming is a method for
writing code interleaved with text. With literate programming, code is
intended to be written in an order that makes sense to a human reader, rather
than a computer.
Producing the human-readable document from the document source is called
"weaving", while producing the computer-readable code is called "tangling". In
this extension, the weaving process is the normal Sphinx rendering process.
For tangling, this extension provides a `tangle` builder — running
`make tangle` will output the computer-readable files in `_build/tangle`.
As is customary with literate programming tools, the extension is also [written
in a literate programming style](code.md).
## Usage
Install the extension by running `pip install literate-sphinx`, and add
`'literate_sphinx'` to the `extensions` list in your `conf.py`.
Code chunks are written using the `literate-code` directive, which takes the
name of the chunk as its argument. It takes the following options:
* `lang`: the language of the chunk. Defaults to `highlight_language`
specified in `conf.py`
* `file`: (takes no value) present if the chunk is a file. If the chunk is a
file, then the code chunk name
* `class`: a list of class names separated by spaces to add to the HTML output
* `padding`: when multiple chunks have the same name, they are written out
sequentially. The `padding` indicates how many blank lines (if any) there
should be between this chunk and the *previous* chunk of the same name.
Defaults to `default_chunk_padding` specified in `conf.py`, which itself
defaults to 1. If given without an argument, one blank line is used.
* `name`: a target name that can be referenced by `ref` or `numref`. This
should not be confused with the code chunk name.
e.g in ReST
```rst
.. literate-code:: code chunk name
:lang: python
def hello():
print("Hello world")
```
or in Markdown using [MyST
parser](https://myst-parser.readthedocs.io/en/latest/index.html)
~~~markdown
```{literate-code} code chunk name
:lang: python
def hello():
print("Hello world")
```
~~~
To include another code chunk, enclose it between `{{` and `}}` delimiters.
Only one code chunk is allowed per line. The code chunk will be prefixed with
everything before the delimiters on the line, and suffixed by everything after
the delimiters.
For example,
```rst
.. literate-code:: file.py
:file:
# before
{{code chunk name}}
# after
```
will produce a file called `file.py` with the contents
```python
# before
def hello():
print("Hello world")
# after
```
and
```rst
.. literate-code:: file.py
:file:
# before
class Hello:
{{code chunk name}} # suffix
# after
```
will produce
```python
# before
class Hello:
def hello(): # suffix
print("Hello world") # suffix
# after
```
The delimiters can be changed by setting the `literate_delimiters` option in
`conf.py`, which takes a tuple, where the first element is the left delimiter
and the second element is the right delimiter. For example:
```python
literate_delimiters = ('<<', '>>')
```
The same code chunk name can be used for multiple chunks; they will be included
in the same order that they appear in the document. If the document is split
across multiple files, they will be processed in the same order as they appear
in the table of contents as defined in the `toctree` directive.
In addition to the `tangle` builder for tangling the document into
computer-readable code files, there is an `annotated-tangle` builder, which
writes the computer-readable code to HTML files, annotated by the chunks that
they come from. You can see an example by viewing the <a
href="_annotated/literate_sphinx.py.html">annotated tangling of this
project</a>.
```{toctree}
---
maxdepth: 2
caption: "More:"
---
code
```
## License
This software may be redistributed under the same license as Sphinx.
```{literate-code} copyright license
:lang: text
Copyright Hubert Chathi <hubert@uhoreg.ca>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
SPDX-License-Identifier: BSD-2-Clause
```
Raw data
{
"_id": null,
"home_page": null,
"name": "literate-sphinx",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "sphinx,literate programming",
"author": null,
"author_email": "Hubert Chathi <hubert@uhoreg.ca>",
"download_url": "https://files.pythonhosted.org/packages/18/b3/ea905416d8cc53aed2ff4cfe1b39d21442e262c1f8462630c47b28df1aef/literate-sphinx-0.1.3.tar.gz",
"platform": null,
"description": "# Literate Sphinx\n\nLiterate Sphinx is a [literate\nprogramming](https://en.wikipedia.org/wiki/Literate_programming) extension for\n[Sphinx](https://www.sphinx-doc.org/). Literate programming is a method for\nwriting code interleaved with text. With literate programming, code is\nintended to be written in an order that makes sense to a human reader, rather\nthan a computer.\n\nProducing the human-readable document from the document source is called\n\"weaving\", while producing the computer-readable code is called \"tangling\". In\nthis extension, the weaving process is the normal Sphinx rendering process.\nFor tangling, this extension provides a `tangle` builder \u2014 running\n`make tangle` will output the computer-readable files in `_build/tangle`.\n\nAs is customary with literate programming tools, the extension is also [written\nin a literate programming style](code.md).\n\n## Usage\n\nInstall the extension by running `pip install literate-sphinx`, and add\n`'literate_sphinx'` to the `extensions` list in your `conf.py`.\n\nCode chunks are written using the `literate-code` directive, which takes the\nname of the chunk as its argument. It takes the following options:\n\n* `lang`: the language of the chunk. Defaults to `highlight_language`\n specified in `conf.py`\n* `file`: (takes no value) present if the chunk is a file. If the chunk is a\n file, then the code chunk name\n* `class`: a list of class names separated by spaces to add to the HTML output\n* `padding`: when multiple chunks have the same name, they are written out\n sequentially. The `padding` indicates how many blank lines (if any) there\n should be between this chunk and the *previous* chunk of the same name.\n Defaults to `default_chunk_padding` specified in `conf.py`, which itself\n defaults to 1. If given without an argument, one blank line is used.\n* `name`: a target name that can be referenced by `ref` or `numref`. This\n should not be confused with the code chunk name.\n\ne.g in ReST\n\n```rst\n.. literate-code:: code chunk name\n :lang: python\n\n def hello():\n print(\"Hello world\")\n```\n\nor in Markdown using [MyST\nparser](https://myst-parser.readthedocs.io/en/latest/index.html)\n\n~~~markdown\n```{literate-code} code chunk name\n:lang: python\n\ndef hello():\n print(\"Hello world\")\n```\n~~~\n\nTo include another code chunk, enclose it between `{{` and `}}` delimiters.\nOnly one code chunk is allowed per line. The code chunk will be prefixed with\neverything before the delimiters on the line, and suffixed by everything after\nthe delimiters.\n\nFor example,\n\n```rst\n.. literate-code:: file.py\n :file:\n # before\n {{code chunk name}}\n # after\n```\n\nwill produce a file called `file.py` with the contents\n\n```python\n# before\ndef hello():\n print(\"Hello world\")\n# after\n```\n\nand\n\n```rst\n.. literate-code:: file.py\n :file:\n # before\n class Hello:\n {{code chunk name}} # suffix\n # after\n```\n\nwill produce\n\n```python\n# before\nclass Hello:\n def hello(): # suffix\n print(\"Hello world\") # suffix\n# after\n```\n\nThe delimiters can be changed by setting the `literate_delimiters` option in\n`conf.py`, which takes a tuple, where the first element is the left delimiter\nand the second element is the right delimiter. For example:\n\n```python\nliterate_delimiters = ('<<', '>>')\n```\n\nThe same code chunk name can be used for multiple chunks; they will be included\nin the same order that they appear in the document. If the document is split\nacross multiple files, they will be processed in the same order as they appear\nin the table of contents as defined in the `toctree` directive.\n\nIn addition to the `tangle` builder for tangling the document into\ncomputer-readable code files, there is an `annotated-tangle` builder, which\nwrites the computer-readable code to HTML files, annotated by the chunks that\nthey come from. You can see an example by viewing the <a\nhref=\"_annotated/literate_sphinx.py.html\">annotated tangling of this\nproject</a>.\n\n```{toctree}\n---\nmaxdepth: 2\ncaption: \"More:\"\n---\ncode\n```\n\n## License\n\nThis software may be redistributed under the same license as Sphinx.\n\n```{literate-code} copyright license\n:lang: text\n\nCopyright Hubert Chathi <hubert@uhoreg.ca>\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are\nmet:\n\n* Redistributions of source code must retain the above copyright\n notice, this list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright\n notice, this list of conditions and the following disclaimer in the\n documentation and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n\"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\nLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\nA PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT\nHOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\nSPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT\nLIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\nDATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\nTHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\nSPDX-License-Identifier: BSD-2-Clause\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A literate programming extension for Sphinx",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://uhoreg.gitlab.io/literate-sphinx/",
"Home": "https://gitlab.com/uhoreg/literate-sphinx/",
"Source": "https://gitlab.com/uhoreg/literate-sphinx"
},
"split_keywords": [
"sphinx",
"literate programming"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6eacf56e57eca98d936116d9dbbc1f5fb4390511ca9d8e057737275128511d2d",
"md5": "f9e9154c08906b23babf6cb7a1a18f76",
"sha256": "950e22e8bddcea36ad459dd8a8bcb91fecfb3a01382671e854556cd7130c6a00"
},
"downloads": -1,
"filename": "literate_sphinx-0.1.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "f9e9154c08906b23babf6cb7a1a18f76",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 8467,
"upload_time": "2023-08-05T00:27:40",
"upload_time_iso_8601": "2023-08-05T00:27:40.029686Z",
"url": "https://files.pythonhosted.org/packages/6e/ac/f56e57eca98d936116d9dbbc1f5fb4390511ca9d8e057737275128511d2d/literate_sphinx-0.1.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "18b3ea905416d8cc53aed2ff4cfe1b39d21442e262c1f8462630c47b28df1aef",
"md5": "05b73c0eebaaac12fbbaa8aa7a404124",
"sha256": "8bb8ee9b177e1830590e1ae035c9a2e32279f4623a48b9c16ad5d9c615aecf91"
},
"downloads": -1,
"filename": "literate-sphinx-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "05b73c0eebaaac12fbbaa8aa7a404124",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19350,
"upload_time": "2023-08-05T00:27:41",
"upload_time_iso_8601": "2023-08-05T00:27:41.842884Z",
"url": "https://files.pythonhosted.org/packages/18/b3/ea905416d8cc53aed2ff4cfe1b39d21442e262c1f8462630c47b28df1aef/literate-sphinx-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-05 00:27:41",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "uhoreg",
"gitlab_project": "literate-sphinx",
"lcname": "literate-sphinx"
}
