savage-lands/share/readmes/sphinx.md

to set up a project for documentation

assuming we are using someproject:

sphinx-apidoc -o /PATH-TO/someproject/docs/source/ /PATH-TO/someproject/

sphinx-build -b html /PATH-TO/someproject/docs/source /PATH-TO/someproject/docs/build/html

cd /PATH-TO/someproject/docs
make html

/PATH-TO/someproject - contains all the source files that we are looking at /PATH-TO/someproject/docs - wherever the sphinx doc files, build, conf, etc are located /PATH-TO/someproject/docs/source - contains the SPHINX configuration info for how to read the source

when setting up sphinx for use with a django app

if you get an error that looks like: sphinx raise AppRegistryNotReady("Apps aren't loaded yet.") django.core.exceptions.AppRegistryNotReady: Apps aren't loaded yet.

from https://stackoverflow.com/questions/34461088/sphinx-apidoc-on-django-build-html-failure-on-django-core-exceptions-appregistr

import django
sys.path.insert(0, os.path.abspath('..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'myproject.settings'
django.setup()

what I did in the drfcryce project for apps.todos:

import os
import sys
import django
sys.path.insert(0, os.path.abspath('../../../'))
sys.path.insert(0, os.path.abspath('../../../../'))

os.environ['DJANGO_SETTINGS_MODULE'] = 'drfcryce._settings.development'
django.setup()

the first two sys.path fixes are to add the apps/todos to do the python path, and to add the drfcryce settings directory to the python path

to set up vim

let g:syntastic_rst_checkers=['sphinx']
let g:syntastic_rst_sphinx_source_dir="/path/to/docs/source" 
let g:syntastic_rst_sphinx_config_dir="/path/to/docs/source"

the first path must lead to where ever index.rst is located the second path must lead to where ever conf.py is located