# sphinxcontrib-jsonglobaltoc
This [Sphinx](http://sphinx-doc.org) extension extends `JSONHTMLBuilder` from
`sphinxcontrib-serializinghtml` to add a `globaltoc` key to each `.fjson` file
produced. `globaltoc` will contain the HTML for the global table of contents
for the entire set of documentation.
## Getting It
You can get `sphinxcontrib-jsonglobaltoc` by using pip:
```bash
pip install sphinxcontrib-jsonglobaltoc
```
If you want to install it from source, grab the git repository from GitHub and run `setup.py`:
```bash
git clone git://github.com/caltechads/sphinxcontrib-jsonglobaltoc.git
cd sphinxcontrib-jsonglobaltoc
python setup.py install
```
## Installing It
To enable `sphinxcontrib-jsonglobaltoc` in your Sphinx project, you need to add
it to `extensions` list in your `conf.py`:
```python
extensions = [
...
'sphinx_json_globaltoc',
...
]
```
## Configuring It
`sphinxcontrib-jsonglobaltoc` adds one configuration option to `conf.py`:
`globaltoc_collapse`, a boolean with a default of `True`.
If `True`, do not add entries to the global table of contents for headings under
the included page. If `False`, do add them.
If you have nested `toctree` blocks, you must set `globaltoc_collapse` to
`False` if you want to see the entries from the nested `toctree` in your
globaltoc.
If `True`
## Using It
In your Sphinx docs folder, produce your `jsonhtml` output like so:
```bash
make json
```
Now if you open one of your `.ftjson` files and examine it, you
should see a `globaltoc` key. For example:
```python
>>> import json
>>> with open('build/json/index.fjson', encoding='utf-8') as index:
... data = json.load(index)
>>> index['globaltoc']
'<ul>\n<li class="toctree-l1"><a class="reference internal" href="page1/">Page 1</a></li>\n<li class="toctree-l1"><a class="reference internal" href="page2/">Page 2</a></li>\n<li class="toctree-l1"><a class="reference internal" href="page3/">Page 3</a></li>\n<li class="toctree-l1"><a class="reference internal" href="page4/">Page 4</a></li>\n<li class="toctree-l1"><a class="reference internal" href="page5/">Page 5</a></li>\n<li class="toctree-l1"><a class="reference internal" href="api/">Developer Interface</a></li>\n</ul>\n'
```
Each `.ftjson` file's ``globaltoc`` key will contain the **full global toc** for the
entire documentation set. We do this so that you can just look at the
``master_doc`` and extract its ``globaltoc`` key to get the sitemap for the
entire set. Otherwise you'd have to walk through every page in the set and
merge their individual HTML blobs into a whole. Not fun.
## How to get nested toctrees to build properly into globaltoc
If you have a single `.. toctree::` declaration in the root page of your
documentation, then it's pretty difficult to make that not render properly into
``globaltoc``.
But if you want nested toctrees, if you don't construct your pages properly,
you'll get a mess in ``globaltoc``.
Let's say that you are writing a book with pages for chapters, and pages for sections
(in chapters) . You want the sections to appear as children to the chapters,
and to not appear in the global table of contents as siblings of the chapters.
To do that in Sphinx, you have to make the root doc `.. toctree::` that lists
only the chapter pages, then have the chapter pages each have toctrees that list their
own section documents.
### An example
Here's `index.rst`, our root document:
```rst
=======
My Book
=======
.. toctree::
:hidden:
chapter1
chapter2
chapter3
Some introduction. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
```
Now for a chapter document, `chapter1.rst`, we list the section pages in its
`.. toctree::`:
```rst
*********
Chapter 1
*********
.. toctree::
:hidden:
chapter1-section1
chapter2-section2
chapter2-section3
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
```
Finally, a section document, `chapter1-section1.rst`:
```rst
Chapter 1, Section 1
====================
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
```
There are three important things to note here:
* You MUST get the heading levels right. The top level document heading must be a
level 1 heading. In ReStructuredText that is `#` underline and overline. The
chapter page must have a level 2 heading. In ReStructuredText that is `*`
underline and overline. If you don't get the heading levels right, you end up with
very odd nesting behavior in the resultant global table of contents.
* Put your `.. toctree::` declaration directly under the page heading. On
sub-pages, the toctree gets its level from the **nearest preceding heading**,
not from the page heading. Thus to ensure that the sub-page toctree gets
inserted into the global toc tree as the right level, you should put your `..
toctree::` declaration right under the page heading.
* If all you're interested in your global table of contents are the page titles, be
sure to do add `:maxdepth: 1` to your `.. toctree::` declaration. You will still
have access to the local table of contents for the headings on the page in the ``toc``
key in the `.fjson` file.
Raw data
{
"_id": null,
"home_page": "https://github.com/caltechads/sphinxcontrib-jsonglobaltoc",
"name": "sphinxcontrib-jsonglobaltoc",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "documentation,sphinx,json",
"author": "Caltech IMSS ADS",
"author_email": "imss-ads-staff@caltech.edu",
"download_url": "https://files.pythonhosted.org/packages/57/23/90ba3ccde1fb123737982b542c1c63d912c33b3b8a0bf33c232888e96864/sphinxcontrib-jsonglobaltoc-0.1.5.tar.gz",
"platform": null,
"description": "# sphinxcontrib-jsonglobaltoc\n\nThis [Sphinx](http://sphinx-doc.org) extension extends `JSONHTMLBuilder` from\n`sphinxcontrib-serializinghtml` to add a `globaltoc` key to each `.fjson` file\nproduced. `globaltoc` will contain the HTML for the global table of contents\nfor the entire set of documentation.\n\n## Getting It\n\nYou can get `sphinxcontrib-jsonglobaltoc` by using pip:\n\n```bash\npip install sphinxcontrib-jsonglobaltoc\n```\n\nIf you want to install it from source, grab the git repository from GitHub and run `setup.py`:\n\n```bash\ngit clone git://github.com/caltechads/sphinxcontrib-jsonglobaltoc.git\ncd sphinxcontrib-jsonglobaltoc\npython setup.py install\n```\n\n## Installing It\n\nTo enable `sphinxcontrib-jsonglobaltoc` in your Sphinx project, you need to add\nit to `extensions` list in your `conf.py`:\n\n```python\nextensions = [\n ...\n 'sphinx_json_globaltoc',\n ...\n]\n```\n\n## Configuring It\n\n`sphinxcontrib-jsonglobaltoc` adds one configuration option to `conf.py`:\n`globaltoc_collapse`, a boolean with a default of `True`.\n\nIf `True`, do not add entries to the global table of contents for headings under\nthe included page. If `False`, do add them.\n\nIf you have nested `toctree` blocks, you must set `globaltoc_collapse` to\n`False` if you want to see the entries from the nested `toctree` in your\nglobaltoc.\n\nIf `True`\n\n## Using It\n\nIn your Sphinx docs folder, produce your `jsonhtml` output like so:\n\n```bash\nmake json\n```\n\nNow if you open one of your `.ftjson` files and examine it, you\nshould see a `globaltoc` key. For example:\n\n```python\n>>> import json\n>>> with open('build/json/index.fjson', encoding='utf-8') as index:\n... data = json.load(index)\n>>> index['globaltoc']\n'<ul>\\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"page1/\">Page 1</a></li>\\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"page2/\">Page 2</a></li>\\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"page3/\">Page 3</a></li>\\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"page4/\">Page 4</a></li>\\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"page5/\">Page 5</a></li>\\n<li class=\"toctree-l1\"><a class=\"reference internal\" href=\"api/\">Developer Interface</a></li>\\n</ul>\\n'\n```\n\nEach `.ftjson` file's ``globaltoc`` key will contain the **full global toc** for the\nentire documentation set. We do this so that you can just look at the\n``master_doc`` and extract its ``globaltoc`` key to get the sitemap for the\nentire set. Otherwise you'd have to walk through every page in the set and\nmerge their individual HTML blobs into a whole. Not fun.\n\n## How to get nested toctrees to build properly into globaltoc\n\nIf you have a single `.. toctree::` declaration in the root page of your\ndocumentation, then it's pretty difficult to make that not render properly into\n``globaltoc``.\n\nBut if you want nested toctrees, if you don't construct your pages properly,\nyou'll get a mess in ``globaltoc``.\n\nLet's say that you are writing a book with pages for chapters, and pages for sections\n(in chapters) . You want the sections to appear as children to the chapters,\nand to not appear in the global table of contents as siblings of the chapters.\n\nTo do that in Sphinx, you have to make the root doc `.. toctree::` that lists\nonly the chapter pages, then have the chapter pages each have toctrees that list their\nown section documents.\n\n### An example\n\nHere's `index.rst`, our root document:\n\n```rst\n=======\nMy Book\n=======\n\n.. toctree::\n :hidden:\n\n chapter1\n chapter2\n chapter3\n\nSome introduction. Lorem ipsum dolor sit amet, consectetur adipiscing elit,\nsed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad\nminim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea\ncommodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit\nesse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat\nnon proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n```\n\nNow for a chapter document, `chapter1.rst`, we list the section pages in its\n`.. toctree::`:\n\n```rst\n*********\nChapter 1\n*********\n\n.. toctree::\n :hidden:\n\n chapter1-section1\n chapter2-section2\n chapter2-section3\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor\nincididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis\nnostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\nDuis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu\nfugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in\nculpa qui officia deserunt mollit anim id est laborum.\n```\n\nFinally, a section document, `chapter1-section1.rst`:\n\n```rst\nChapter 1, Section 1\n====================\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor\nincididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis\nnostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\nDuis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu\nfugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in\nculpa qui officia deserunt mollit anim id est laborum.\n```\n\nThere are three important things to note here:\n\n* You MUST get the heading levels right. The top level document heading must be a\n level 1 heading. In ReStructuredText that is `#` underline and overline. The\n chapter page must have a level 2 heading. In ReStructuredText that is `*`\n underline and overline. If you don't get the heading levels right, you end up with\n very odd nesting behavior in the resultant global table of contents.\n\n* Put your `.. toctree::` declaration directly under the page heading. On\n sub-pages, the toctree gets its level from the **nearest preceding heading**,\n not from the page heading. Thus to ensure that the sub-page toctree gets\n inserted into the global toc tree as the right level, you should put your `..\n toctree::` declaration right under the page heading.\n\n* If all you're interested in your global table of contents are the page titles, be\n sure to do add `:maxdepth: 1` to your `.. toctree::` declaration. You will still\n have access to the local table of contents for the headings on the page in the ``toc``\n key in the `.fjson` file.\n",
"bugtrack_url": null,
"license": "",
"summary": "Sphinx extension to add a global table of contents to JSON output files",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/caltechads/sphinxcontrib-jsonglobaltoc",
"Issues": "https://github.com/caltechads/sphinxcontrib-jsonglobaltoc/issues",
"Source": "https://github.com/caltechads/sphinxcontrib-jsonglobaltoc"
},
"split_keywords": [
"documentation",
"sphinx",
"json"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6e3ede8c7adbc1c95f315c7ecae42d65c2791821c8a04b177393d13a6322b1e1",
"md5": "5494458a96846b4a8d5083b9bd52a496",
"sha256": "8fdcae26dee7af68fb3346d94f514105298ea70492f72bd7d9cf9884ce5a4d03"
},
"downloads": -1,
"filename": "sphinxcontrib_jsonglobaltoc-0.1.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5494458a96846b4a8d5083b9bd52a496",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 6256,
"upload_time": "2023-09-15T22:06:58",
"upload_time_iso_8601": "2023-09-15T22:06:58.772884Z",
"url": "https://files.pythonhosted.org/packages/6e/3e/de8c7adbc1c95f315c7ecae42d65c2791821c8a04b177393d13a6322b1e1/sphinxcontrib_jsonglobaltoc-0.1.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "572390ba3ccde1fb123737982b542c1c63d912c33b3b8a0bf33c232888e96864",
"md5": "d72890724302d2f56cedc7c8c1103706",
"sha256": "be828859c878c8e9a9beca9b37d073ae2c2651b60e068826dc8fdbb9c865c6b0"
},
"downloads": -1,
"filename": "sphinxcontrib-jsonglobaltoc-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "d72890724302d2f56cedc7c8c1103706",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6333,
"upload_time": "2023-09-15T22:07:00",
"upload_time_iso_8601": "2023-09-15T22:07:00.553330Z",
"url": "https://files.pythonhosted.org/packages/57/23/90ba3ccde1fb123737982b542c1c63d912c33b3b8a0bf33c232888e96864/sphinxcontrib-jsonglobaltoc-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-15 22:07:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "caltechads",
"github_project": "sphinxcontrib-jsonglobaltoc",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "sphinxcontrib-jsonglobaltoc"
}
JSON
