Django-mkdocs is built on the premise that there is a need for simple, beautiful, maintainable documentation which can be user-permissioned. The app is *heavily inspired* by [django-documentation](https://github.com/Narsil/django-documentation) with updated compatibility for Django 1.10, and uses [MkDocs](http://www.mkdocs.org/) to generate a static-site served by Django.
To be clear, django-mkdocs was not intended for large-scale access. It was originally created to serve documentation internally and to select partners. If your documents are intended to be public, using MkDocs alone with github-pages or Amazon S3 may be a better solution.
Django-mkdocs can be installed directly from pip:
$ pip install django-mkdocs
### Plugging django-mkdocs into your Django project
In your Django project, add 'django_mkdocs' to your settings.py:
INSTALLED_APPS = (
Add a reference to your projects urls.py:
from django.conf.urls import url, include
urlpatterns = [
url(r'^docs/', include('django_mkdocs.urls', namespace='documentation')),
### Setting up the MkDocs documentation
MkDocs is included with django-mkdocs. The project naturally has excellent documentation and is linked [here](http://www.mkdocs.org/)
We recommend making a directory for your documentation in the root of your Django project, and starting a MkDocs project in there.
$ mkdocs new project_docs
Your directory structure should now look something like this:
│ ├── __init__.py
│ ├── settings.py
│ ├── urls.py
│ └── wsgi.py
│ └── index.md
The main configuration file for MkDocs is mkdocs.yml. Let's move it into the Django project root for easier builds later on:
$ mv project_docs/mkdocs.yml ./mkdocs.yml
Now we'll need to change a couple of references in this file.
- **site_name** is the title of your HTML page
- **pages** tells MkDocs your desired site-structure and which markdown files should be used to generate it
- **docs_dir** refers to the markdown your documentation will be generated from, while
- **site_dir** refers to the location where the static site will be generated.
- Lastly, **use_directory_urls** should be set to false for Django's routing to work correctly.
site_name: My Docs
- Home: index.md
To build the documentation, run the following command from the directory containing mkdocs.yml. We include the optional *--clean* flag here to signify that site_dir should be cleansed of page references that have been removed from our mkdocs.yml.
$ mkdocs build --clean
It's also recommended that you add this command to your post-deployment script for fresh document builds each time you deploy.
### Options for serving the documentation
In order to serve your docs, django-mkdocs needs to know where to look for them. These settings must be configured in your project's settings.py. Set the DOCUMENTATION_ROOT to the directory which contains both your **docs_dir** and **site_dir** folders. In this snippet, 'PROJECT_DIR' is the absolute path to our Django project.
# django-mkdocs demo parameters!
PROJECT_DIR = os.path.dirname(os.path.dirname(__file__))
DOCUMENTATION_ROOT = PROJECT_DIR + '/project_docs'
DOCUMENTATION_HTML_ROOT points to the root of our statically generated site. This should correspond to the same directory as our mkdocs.yml site_dir.
DOCUMENTATION_HTML_ROOT = DOCUMENTATION_ROOT + '/site'
DOCUMENTATION_ACCESS_FUNCTION is used in the views that attempt to access the documentation. Django-mkdocs calls DOCUMENTATION_ACCESS_FUNCTION with request.user as an argument. This flag determines who has access to view the docs.
DOCUMENTATION_ACCESS_FUNCTION = lambda user: user.is_staff
Django-mkdocs assumes an Nginx server is used by default to serve the documentation. DOCUMENTATION_XSENDFILE is set to true by default. If you are not using Nginx, expect a very small number of users, and understand the consequences of using django.views.static.serve, set the following flag:
DOCUMENTATION_XSENDFILE = False
## Viewing your documentation
With the above steps completed, you should now be able to view your static site at the endpoint defined in your project's urlconf. Let's test this out locally. First, run Django's development server from the project root:
$ python manage.py runserver
Point your browser to localhost:8000/docs (or the url you referenced). You should now see your generated docs!
NOTE: If following along in the demo project, you may need to run migrations and create a superuser. You will also need to authenticate at the django admin console at localhost:8000/admin after performing the following commands.
$ python manage.py migrate
$ python manage.py createsuperuser
TODO: Brief introduction on what you do with files - including link to relevant help section.