52 lines
1.8 KiB
Markdown
52 lines
1.8 KiB
Markdown
|
## 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
|
||
|
|
|