...
| Code Block | ||||
|---|---|---|---|---|
| ||||
diff --git b/docs/conf.py a/docs/conf.py
index 55c2351..dc4c7a4 100644
--- b/docs/conf.py
+++ a/docs/conf.py
@@ -12,22 +12,37 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+import datetime
+import django
+from recommonmark.parser import CommonMarkParser
+django_version = ".".join(map(str, django.VERSION[0:2]))
+python_version = ".".join(map(str, sys.version_info[0:2]))
+
+sys.path.insert(0, os.path.abspath('..'))
+
+os.environ['DJANGO_SETTINGS_MODULE'] = 'training.settings'
+django.setup()
# -- Project information -----------------------------------------------------
+# See https://pypi.org/project/sphinxcontrib-django/
project = 'Django JSON{json:APIapi} training'
-copyright = '2018, Alan Crosswell'
+year = datetime.date.today().year
+copyright = '{}, The Trustees of Columbia University in the City of New York'.format(year)
author = 'Alan Crosswell'
# The short X.Y version
-version = ''
+from myapp import VERSION
+version = VERSION
# The full version, including alpha/beta/rc tags
-release = ''
+release = VERSION
+# Auto-generate API documentation.
+#os.environ['SPHINX_APIDOC_OPTIONS'] = "members,undoc-members,show-inheritance"
+os.environ['SPHINX_APIDOC_OPTIONS'] = "members,show-inheritance"
# -- General configuration ---------------------------------------------------
@@ -39,23 +54,30 @@ release = ''
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
- 'sphinx.ext.autodoc',
- 'sphinx.ext.intersphinx',
- 'sphinx.ext.todo',
- 'sphinx.ext.viewcode',
+ 'sphinxcontrib.apidoc', # runs sphinx-apidoc automatically as part of sphinx-build
+ 'sphinx.ext.autodoc', # the autodoc extensions uses files generated by apidoc
+ 'sphinxcontrib_django', # does some nicer django autodoc formatting, but:
+ # https://github.com/edoburu/sphinxcontrib-django/issues/12
+ 'sphinx.ext.viewcode', # enable viewing autodoc'd code
+ 'sphinx.ext.intersphinx', # make links between different sphinx-documented packages
+ 'sphinx.ext.todo', # TODO: figure out how to use this;-)
+ 'sphinx_markdown_tables', # CommonMark doesn't do tables: This extensions does!
+ 'sphinxcontrib.confluencebuilder', # supposedly installs docs on Confluence
]
-
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
+source_parsers = {
+ '.md': CommonMarkParser,
+}
+
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -67,7 +89,7 @@ language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['build']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
@@ -78,13 +100,23 @@ pygments_style = None
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
-html_theme = 'alabaster'
+# html_theme = 'alabaster'
+# html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
-# html_theme_options = {}
+html_theme_options = {
+ # these are for sphinx_rtd_theme:
+ 'prev_next_buttons_location': 'both',
+ 'collapse_navigation': True,
+ # these are for alabaster:
+ # 'show_relbars': True,
+ # 'fixed_sidebar': True,
+ # 'sidebar_collapse': True,
+}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
@@ -99,8 +131,16 @@ html_static_path = ['_static']
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
-# html_sidebars = {}
-
+# also for alabaster theme:
+# html_sidebars = {
+# '**': [
+# 'about.html',
+# 'navigation.html',
+# 'relations.html',
+# 'searchbox.html',
+# 'donate.html',
+# ]
+# }
# -- Extension configuration -------------------------------------------------
+autodoc_member_order = 'bysource'
+autodoc_inherit_docstrings = False
+
+apidoc_module_dir = '../myapp'
+apidoc_output_dir = 'apidoc'
+apidoc_excluded_paths = ['../myapp/migrations']
+apidoc_separate_modules = True
+apidoc_toc_file = False
+apidoc_module_first = True
+apidoc_extra_args = ['-f']
+
+confluence_publish = False # for now until we figure out how to make it work.
+confluence_space_name = os.environ.get('CONFLUENCE_SPACE', None)
+confluence_parent_page = os.environ.get('CONFLUENCE_PARENT', None)
+confluence_server_url = "https://confluence.columbia.edu"
+confluence_server_user = os.environ.get('CONFLUENCE_USER', None)
+confluence_ask_password = True
+# confluence_server_pass = os.environ['CONFLUENCE_PASS']
+
# -- Options for intersphinx extension ---------------------------------------
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {
+ 'python': ('https://docs.python.org/{}'.format(python_version), None),
+ 'django': ('https://docs.djangoproject.com/en/{}/'.format(django_version),
+ 'https://docs.djangoproject.com/en/{}/_objects/'.format(django_version)),
+ # not sure why but the default lookup of objects.inv fails with None
+ 'djangorestframework-jsonapi': ('https://django-rest-framework-json-api.readthedocs.io/en/stable/',
+ 'https://django-rest-framework-json-api.readthedocs.io/en/stable/objects.inv'),
+ # DRF doesn't use sphinx but rather mkdocs:-(
+ #'djangorestframework': ('https://django-rest-framework.readthedocs.io/en/stable/', None),
+}
|
...