Briq/django-polymorphic
8
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add API documentation to the package!

Browse Source
This commit is contained in:
Diederik van der Boor
2017-01-09 16:53:12 +01:00
parent c76cc663e0
commit f9fffc44c1
25 changed files with 397 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/_ext/djangodummy/__init__.py
View File
docs/_ext/djangodummy/requirements.txt
+3
View File
@@ -0,0 +1,3 @@
# for readthedocs
# Remaining requirements are picked up from setup.py
Django==1.5.10
docs/_ext/djangodummy/settings.py
+11
View File
@@ -0,0 +1,11 @@
# Settings file to allow parsing API documentation of Django modules,
# and provide defaults to use in the documentation.
#
# This file is placed in a subdirectory,
# so the docs root won't be detected by find_packages()
# Display sane URLs in the docs:
STATIC_URL = '/static/'
# Avoid error for missing the secret key
SECRET_KEY = 'docs'
docs/_ext/djangoext/__init__.py
View File
docs/_ext/djangoext/docstrings.py
+47
View File
@@ -0,0 +1,47 @@
"""
Automatically mention all model fields as parameters in the model construction.
Based on http://djangosnippets.org/snippets/2533/
"""
import django
from django.utils.html import strip_tags
from django.utils.encoding import force_unicode
import inspect
def improve_model_docstring(app, what, name, obj, options, lines):
from django.db import models # must be inside the function, to allow settings initialization first.
if inspect.isclass(obj) and issubclass(obj, models.Model):
if django.VERSION >= (1,8):
model_fields = obj._meta.get_fields()
elif django.VERSION >= (1,6):
model_fields = obj._meta.fields
else:
model_fields = obj._meta._fields()
for field in model_fields:
help_text = strip_tags(force_unicode(field.help_text))
verbose_name = force_unicode(field.verbose_name).capitalize()
# Add parameter
if help_text:
lines.append(u':param %s: %s' % (field.attname, help_text))
else:
lines.append(u':param %s: %s' % (field.attname, verbose_name))
# Add type
if isinstance(field, models.ForeignKey):
to = field.rel.to
lines.append(u':type %s: %s to :class:`~%s.%s`' % (field.attname, type(field).__name__, to.__module__, to.__name__))
else:
lines.append(u':type %s: %s' % (field.attname, type(field).__name__))
# Return the extended docstring
return lines
# Allow this module to be used as sphinx extension:
def setup(app):
# Generate docstrings for Django model fields
# Register the docstring processor with sphinx
app.connect('autodoc-process-docstring', improve_model_docstring)
docs/_ext/djangoext/roles.py
+8
View File
@@ -0,0 +1,8 @@
# Allow :django:setting:`SITE_ID` to work.
def setup(app):
app.add_crossref_type(
directivename = "setting",
rolename = "setting",
indextemplate = "pair: %s; setting",
)
docs/api/index.rst
+13
View File
@@ -0,0 +1,13 @@
API Documentation
=================
.. toctree::
polymorphic.admin
polymorphic.contrib.extra_views
polymorphic.contrib.guardian
polymorphic.formsets
polymorphic.managers
polymorphic.models
polymorphic.templatetags
polymorphic.utils
docs/api/polymorphic.admin.rst
+93
View File
@@ -0,0 +1,93 @@
polymorphic.admin
=================
ModelAdmin classes
------------------
The ``PolymorphicParentModelAdmin`` class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: polymorphic.admin.PolymorphicParentModelAdmin
:members:
:undoc-members:
:show-inheritance:
The ``PolymorphicChildModelAdmin`` class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: polymorphic.admin.PolymorphicChildModelAdmin
:members:
:undoc-members:
:show-inheritance:
List filtering
--------------
The ``PolymorphicChildModelFilter`` class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: polymorphic.admin.PolymorphicChildModelFilter
:show-inheritance:
Inlines support
---------------
The ``StackedPolymorphicInline`` class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: polymorphic.admin.StackedPolymorphicInline
:show-inheritance:
The ``GenericStackedPolymorphicInline`` class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: polymorphic.admin.GenericStackedPolymorphicInline
:members:
:undoc-members:
:show-inheritance:
The ``PolymorphicInlineSupportMixin`` class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: polymorphic.admin.PolymorphicInlineSupportMixin
:members:
:undoc-members:
:show-inheritance:
Low-level classes
-----------------
These classes are useful when existing parts of the admin classes.
.. autoclass:: polymorphic.admin.PolymorphicModelChoiceForm
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: polymorphic.admin.PolymorphicInlineModelAdmin
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: polymorphic.admin.GenericPolymorphicInlineModelAdmin
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: polymorphic.admin.PolymorphicInlineAdminForm
:show-inheritance:
.. autoclass:: polymorphic.admin.PolymorphicInlineAdminFormSet
:show-inheritance:
docs/api/polymorphic.contrib.extra_views.rst
+7
View File
@@ -0,0 +1,7 @@
polymorphic.contrib.extra_views
===============================
.. automodule:: polymorphic.contrib.extra_views
:members:
:undoc-members:
:show-inheritance:
docs/api/polymorphic.contrib.guardian.rst
+7
View File
@@ -0,0 +1,7 @@
polymorphic.contrib.guardian
============================
.. automodule:: polymorphic.contrib.guardian
:members:
:undoc-members:
:show-inheritance:
docs/api/polymorphic.formsets.rst
+41
View File
@@ -0,0 +1,41 @@
polymorphic.formsets
====================
.. automodule:: polymorphic.formsets
Model formsets
--------------
.. autofunction:: polymorphic.formsets.polymorphic_modelformset_factory
.. autoclass:: polymorphic.formsets.PolymorphicFormSetChild
Inline formsets
---------------
.. autofunction:: polymorphic.formsets.polymorphic_inlineformset_factory
Generic formsets
----------------
.. autofunction:: polymorphic.formsets.generic_polymorphic_inlineformset_factory
Low-level features
------------------
The internal machinery can be used to extend the formset classes. This includes:
.. autofunction:: polymorphic.formsets.polymorphic_child_forms_factory
.. autoclass:: polymorphic.formsets.BasePolymorphicModelFormSet
:show-inheritance:
.. autoclass:: polymorphic.formsets.BasePolymorphicInlineFormSet
:show-inheritance:
.. autoclass:: polymorphic.formsets.BaseGenericPolymorphicInlineFormSet
:show-inheritance:
docs/api/polymorphic.managers.rst
+21
View File
@@ -0,0 +1,21 @@
polymorphic.managers
====================
.. automodule:: polymorphic.managers
The ``PolymorphicManager`` class
--------------------------------
.. autoclass:: polymorphic.managers.PolymorphicManager
:members:
:show-inheritance:
The ``PolymorphicQuerySet`` class
---------------------------------
.. autoclass:: polymorphic.managers.PolymorphicQuerySet
:members:
:show-inheritance:
docs/api/polymorphic.models.rst
+8
View File
@@ -0,0 +1,8 @@
polymorphic.models
==================
.. automodule:: polymorphic.models
.. autoclass:: polymorphic.models.PolymorphicModel
:members:
:show-inheritance:
docs/api/polymorphic.templatetags.rst
+4
View File
@@ -0,0 +1,4 @@
polymorphic.templatetags.polymorphic_admin_tags
===============================================
.. automodule:: polymorphic.templatetags
docs/api/polymorphic.utils.rst
+5
View File
@@ -0,0 +1,5 @@
polymorphic.utils
=================
.. automodule:: polymorphic.utils
:members:
docs/conf.py
+14 -3
View File
@@ -13,6 +13,8 @@
import sys
import os
import django
import sphinx_rtd_theme
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
@@ -21,6 +23,9 @@ sys.path.insert(0, os.path.abspath('_ext'))
sys.path.insert(0, os.path.abspath('..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'djangodummy.settings'
if django.VERSION >= (1, 8):
django.setup()
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
@@ -31,7 +36,9 @@ os.environ['DJANGO_SETTINGS_MODULE'] = 'djangodummy.settings'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.graphviz',
'sphinx.ext.intersphinx'
'sphinx.ext.intersphinx',
'djangoext.docstrings',
'djangoext.roles',
]
# Add any paths that contain templates here, relative to this directory.
@@ -98,7 +105,8 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# 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
@@ -252,5 +260,8 @@ texinfo_documents = [
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
#'http://docs.python.org/': None,
'https://docs.djangoproject.com/en/dev': 'https://docs.djangoproject.com/en/dev/_objects',
'https://docs.djangoproject.com/en/stable': 'https://docs.djangoproject.com/en/stable/_objects',
}
# autodoc settings
autodoc_member_order = 'groupwise'
docs/index.rst
+7 -3
View File
@@ -1,8 +1,9 @@
Welcome to django-polymorphic's documentation!
==============================================
Django-polymorphic simplifies using inherited models in Django projects.
When a query is made at the base model, the inherited model classes are returned.
Django-polymorphic builds on top of the standard Django model inheritance.
It makes using inherited models easier. When a query is made at the base model,
the inherited model classes are returned.
When we store models that inherit from a ``Project`` model...
@@ -43,6 +44,7 @@ Features
* Combining querysets of different models (``qs3 = qs1 | qs2``)
* Support for custom user-defined managers.
* Formset support.
* Uses the minimum amount of queries needed to fetch the inherited models.
* Disabling polymorphic behavior when needed.
@@ -56,6 +58,7 @@ Getting started
quickstart
admin
performance
third-party
Advanced topics
---------------
@@ -67,9 +70,10 @@ Advanced topics
migrating
managers
advanced
third-party
changelog
contributing
api/index
Indices and tables
==================
docs/third-party.rst
+33 -19
View File
@@ -2,6 +2,35 @@ Third-party applications support
================================
django-guardian support
-----------------------
.. versionadded:: 1.0.2
You can configure django-guardian_ to use the base model for object level permissions.
Add this option to your settings:
.. code-block:: python
GUARDIAN_GET_CONTENT_TYPE = 'polymorphic.contrib.guardian.get_polymorphic_base_content_type'
This option requires django-guardian_ >= 1.4.6. Details about how this option works are available in the
`django-guardian documentation <https://django-guardian.readthedocs.io/en/latest/configuration.html#guardian-get-content-type>`_.
django-extra-views
------------------
.. versionadded:: 1.1
The :mod:`polymorphic.contrib.extra_views` package provides classes to display polymorphic formsets
using the classes from django-extra-views_. See the documentation of:
* :class:`~polymorphic.contrib.extra_views.PolymorphicFormSetView`
* :class:`~polymorphic.contrib.extra_views.PolymorphicInlineFormSetView`
* :class:`~polymorphic.contrib.extra_views.PolymorphicInlineFormSet`
django-mptt support
-------------------
@@ -97,24 +126,9 @@ This doesn't work, since it needs to look for revisions of the child model. Usin
the view of the actual child model is used, similar to the way the regular change and delete views are redirected.
django-guardian support
-----------------------
.. versionadded:: 1.0.2
You can configure django-guardian_ to use the base model for object level permissions.
Add this option to your settings:
.. code-block:: python
GUARDIAN_GET_CONTENT_TYPE = 'polymorphic.contrib.guardian.get_polymorphic_base_content_type'
This option requires django-guardian_ >= 1.4.6. Details about how this option works are available in the
`django-guardian documentation <https://django-guardian.readthedocs.io/en/latest/configuration.html#guardian-get-content-type>`_.
.. _django-reversion: https://github.com/etianen/django-reversion
.. _django-reversion-compare: https://github.com/jedie/django-reversion-compare
.. _django-extra-views: https://github.com/AndrewIngram/django-extra-views
.. _django-guardian: https://github.com/django-guardian/django-guardian
.. _django-mptt: https://github.com/django-mptt/django-mptt
.. _django-polymorphic-tree: https://github.com/django-polymorphic/django-polymorphic-tree
.. _django-guardian: https://github.com/django-guardian/django-guardian
.. _django-reversion-compare: https://github.com/jedie/django-reversion-compare
.. _django-reversion: https://github.com/etianen/django-reversion