Skip to content

Document structured JSON documents with Sphinx

Notifications You must be signed in to change notification settings

Memrise/sphinx-jsondomain

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

27 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Sphinx JSON Domain

https://img.shields.io/pypi/v/sphinx-jsondomain.svg?maxAge=2592000 https://readthedocs.org/projects/sphinx-jsondomain/badge/?version=latest https://travis-ci.org/dave-shawley/sphinx-jsondomain.svg?branch=master

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.

About

Document structured JSON documents with Sphinx

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Python 100.0%