Describe JSON document structures in sphinx
Project description
I was surprised that this didn’t already exist somewhere when I wanted to describe a JSON document outside of using sphinxcontrib-httpdomain to document one of my APIs. This extension simplifies describing structured JSON documents using a new Sphinx domain.
.. json:object:: Github User
What Github's API thinks a user looks like.
:property string login: the user's login
:property integer id: Github assigned unique user identifier
:property string avatar_url: url to user's selected avatar image
or the empty string
:property string gravatar_url: url to the user's gravatar image
or the empty string
This will format to something pretty and make references to :json:object:`Github User` work as expected. See the online examples for a better idea of what is possible.
Quick Start
Install sphinx and the sphinx-jsondomain package:
$ python3 -mvenv env $ env/bin/pip install -q sphinx sphinx-jsondomain
Set up the sphinx documentation root and build your documentation set:
$ env/bin/sphinx-quickstart -p my-project -r 0.0 -v 0.0.0 \ > -a 'Dave Shawley <daveshawley@gmail.com>' --quiet docs $ env/bin/sphinx-build -b html docs build/sphinx/html
Now, find the extensions definition in docs/conf.py and add sphinxjsondomain to the end. Add a json:object directive to docs/index.rst and run sphinx-build again to see the results.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx_jsondomain-0.0.2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 98e4214821631073363e48dcfa8235b210066d1fab22c2294f2a73fff92b6155 |
|
MD5 | f7976c1ae0017e1d0d972100d744f3eb |
|
BLAKE2b-256 | 7d7357492e375ccc447b72eedcd0ac0d11b9e42beb7300c19948306786f511ac |