Modular documentation generator for rest framwork apis
Project description
Django REST Framework APIDoc
============================
Library to better documentation system for Django REST framework.
This support file based documentation and other markup languages like RestructuredText or Textile.
Configuration
-------------
To configure apidoc in djangorestframework version <= 2.3.8, you need to monkey
patch it. Add this line in a very first loaded models module
.. code:: python
from rest_framework_apidoc.monkey import patch_api_view; patch_api_view()
Then you have to configure your `VIEW_DESCRIPTION_FUNCTION` of `REST_FRAMEWORK`
setting to use the rest_framework_apidoc version:
.. code:: python
REST_FRAMEWORK = {
...,
'VIEW_DESCRIPTION_FUNCTION': 'rest_framework_apidoc.apidoc.get_view_description',
...,
}
Then you can configure your apidoc default documenter classes:
.. code:: python
APIDOC_DEFAULT_DOCUMENTER_CLASSES = ['rest_framework_apidoc.apidoc.MDDocStringDocumenter']
The `APIDOC_DEFAULT_DOCUMENTER_CLASSES` default value is `['rest_framework_apidoc.apidoc.MDDocStringsDocumenter']`
If you use file based documentation, you can set the path to your documentation files:
You can override the default setting for a APIView adding the attribute `documenter_classes`.
.. code:: python
APIDOC_DOCUMENTATION_PATH = "my-api-documentation"
The `APIDOC_DOCUMENTATION_PATH` default value is `apidoc`
APIDoc Mixins
-------------
The documenter classes are composed by 2 types of mixings, the content mixins
and the process mixins. The content mixins obtain the documentation text, and
the process mixing transform this text in another thing.
Content mixins
~~~~~~~~~~~~~~
* **FileContentMixin**: Get the content from a file named like the url_name +
extension attribute of the class (if exists), and placed in the
`APIDOC_DOCUMENTATION_PATH`.
* **DocStringContentMixin**: Get the content from the APIView doc string.
Process mixins
~~~~~~~~~~~~~~
* **MarkupProcessMixin**: Use django-markup to convert to html the content, based
on the markup class attribute.
* **NoProcessMixin**: Do nothing
* **SafeProcessMixin**: Mark as safe the content.
Documenter Classes
------------------
RSTFilesDocumenter
~~~~~~~~~~~~~~~~~~
Composed by FileContentMixin and MarkupProcessMixin with extension = ".rst" and markup = "restructuredtext"
RSTDocStringsDocumenter
~~~~~~~~~~~~~~~~~~~~~~~
Composed by DocStringContentMixin and MarkupProcessMixin with markup = "restructuredtext"
MDFilesDocumenter
~~~~~~~~~~~~~~~~~
Composed by FileContentMixin and MarkupProcessMixin with extension = ".md" and markup = "markdown"
MDDocStringsDocumenter
~~~~~~~~~~~~~~~~~~~~~~
Composed by DocStringContentMixin and MarkupProcessMixin with markup = "markdown"
TextileFilesDocumenter
~~~~~~~~~~~~~~~~~~~~~~
Composed by FileContentMixin and MarkupProcessMixin with extension = ".textile" and markup = "textile"
TextileDocStringsDocumenter
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Composed by DocStringContentMixin and MarkupProcessMixin with markup = "textile"
TxtFilesDocumenter
~~~~~~~~~~~~~~~~~~
Composed by FileContentMixin and NoProcessMixin with extension = ".txt"
TxtDocStringsDocumenter
~~~~~~~~~~~~~~~~~~~~~~~
Composed by DocStringContentMixin and NoProcessMixin
HtmlFilesDocumenter
~~~~~~~~~~~~~~~~~~~
Composed by FileContentMixin, SafeProcessMixin with extension = ".html"
HtmlDocStringsDocumenter
~~~~~~~~~~~~~~~~~~~~~~~~
Composed by DocStringContentMixin and SafeProcessMixin
============================
Library to better documentation system for Django REST framework.
This support file based documentation and other markup languages like RestructuredText or Textile.
Configuration
-------------
To configure apidoc in djangorestframework version <= 2.3.8, you need to monkey
patch it. Add this line in a very first loaded models module
.. code:: python
from rest_framework_apidoc.monkey import patch_api_view; patch_api_view()
Then you have to configure your `VIEW_DESCRIPTION_FUNCTION` of `REST_FRAMEWORK`
setting to use the rest_framework_apidoc version:
.. code:: python
REST_FRAMEWORK = {
...,
'VIEW_DESCRIPTION_FUNCTION': 'rest_framework_apidoc.apidoc.get_view_description',
...,
}
Then you can configure your apidoc default documenter classes:
.. code:: python
APIDOC_DEFAULT_DOCUMENTER_CLASSES = ['rest_framework_apidoc.apidoc.MDDocStringDocumenter']
The `APIDOC_DEFAULT_DOCUMENTER_CLASSES` default value is `['rest_framework_apidoc.apidoc.MDDocStringsDocumenter']`
If you use file based documentation, you can set the path to your documentation files:
You can override the default setting for a APIView adding the attribute `documenter_classes`.
.. code:: python
APIDOC_DOCUMENTATION_PATH = "my-api-documentation"
The `APIDOC_DOCUMENTATION_PATH` default value is `apidoc`
APIDoc Mixins
-------------
The documenter classes are composed by 2 types of mixings, the content mixins
and the process mixins. The content mixins obtain the documentation text, and
the process mixing transform this text in another thing.
Content mixins
~~~~~~~~~~~~~~
* **FileContentMixin**: Get the content from a file named like the url_name +
extension attribute of the class (if exists), and placed in the
`APIDOC_DOCUMENTATION_PATH`.
* **DocStringContentMixin**: Get the content from the APIView doc string.
Process mixins
~~~~~~~~~~~~~~
* **MarkupProcessMixin**: Use django-markup to convert to html the content, based
on the markup class attribute.
* **NoProcessMixin**: Do nothing
* **SafeProcessMixin**: Mark as safe the content.
Documenter Classes
------------------
RSTFilesDocumenter
~~~~~~~~~~~~~~~~~~
Composed by FileContentMixin and MarkupProcessMixin with extension = ".rst" and markup = "restructuredtext"
RSTDocStringsDocumenter
~~~~~~~~~~~~~~~~~~~~~~~
Composed by DocStringContentMixin and MarkupProcessMixin with markup = "restructuredtext"
MDFilesDocumenter
~~~~~~~~~~~~~~~~~
Composed by FileContentMixin and MarkupProcessMixin with extension = ".md" and markup = "markdown"
MDDocStringsDocumenter
~~~~~~~~~~~~~~~~~~~~~~
Composed by DocStringContentMixin and MarkupProcessMixin with markup = "markdown"
TextileFilesDocumenter
~~~~~~~~~~~~~~~~~~~~~~
Composed by FileContentMixin and MarkupProcessMixin with extension = ".textile" and markup = "textile"
TextileDocStringsDocumenter
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Composed by DocStringContentMixin and MarkupProcessMixin with markup = "textile"
TxtFilesDocumenter
~~~~~~~~~~~~~~~~~~
Composed by FileContentMixin and NoProcessMixin with extension = ".txt"
TxtDocStringsDocumenter
~~~~~~~~~~~~~~~~~~~~~~~
Composed by DocStringContentMixin and NoProcessMixin
HtmlFilesDocumenter
~~~~~~~~~~~~~~~~~~~
Composed by FileContentMixin, SafeProcessMixin with extension = ".html"
HtmlDocStringsDocumenter
~~~~~~~~~~~~~~~~~~~~~~~~
Composed by DocStringContentMixin and SafeProcessMixin
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Close
Hashes for djangorestframework-apidoc-0.0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 22f90a7ce3490133ad6c21af670a47a7f8f8f1b014e0b097c11af7ff4c83a13d |
|
MD5 | e01bfcd7c0dfbc35200016bc39bc94e7 |
|
BLAKE2b-256 | 5fb7ca36fe2dc41771b21d8f472970fd840d98414086cd77a864acb0f21bb49b |