Skip to content

Commit c9dcc9c

Browse files
author
Emmanouil Konstantinidis
committed
Init MKdocs
1 parent a5af900 commit c9dcc9c

14 files changed

+350
-0
lines changed

Diff for: ‎docs/changelog.md

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: "Changelog"
3+
source_filename: "changelog"
4+
order: 8
5+
---
6+
7+
### Release 0.0.7
8+
9+
- Fix methods in Live API Endpoints (now compatible with Python 2.7)
10+
- Remove `.<format>` from urls
11+
- Fixed a bug that removes double slashes from the endpoint's url
12+
13+
14+
### Release 0.0.6
15+
16+
- Introducing Live API Endpoints - Test your endpoints from within the docs
17+
- Setting `HIDDEN` is now `HIDE_DOCS`
18+
19+
20+
### Release 0.0.5
21+
22+
- Support both common types of ROOT_URLCONF
23+
24+
25+
### Release 0.0.4
26+
27+
- Allow templates overrides
28+
- More template `blocks` to be overridden
29+
- Improved MANIFEST.in
30+
- Exclude `node_modules/`
31+
32+
33+
### Release 0.0.3
34+
35+
- Fixes a bug where Django's `collectstatic` command was failing because of Glyphicons
36+
37+
38+
### Release 0.0.2
39+
40+
- Search between endpoint paths
41+
- Display docstring for each endpoint
42+
43+
44+
### Release 0.0.1
45+
46+
First release of the project to [pypi](https://pypi.python.org/pypi). Features include:
47+
48+
- List all endpoints that inherit from DRF's `APIView`
49+
- Settings to hide docs view (ie. in Production)
50+
- Override Templates
51+
- Support for Python 2.7, 3.3, 3.4, 3.5
52+
- Support for Django 1.8, 1.9
53+
- Support for Django REST Framework 3 and above

Diff for: ‎docs/contributing.md

+100
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: "Contributing & Development"
3+
source_filename: "contributing"
4+
order: 7
5+
---
6+
7+
### Development
8+
If you want to **use the demo** app to work on this package:
9+
10+
In the project [repository](https://github.com/ekonstantinidis/django-rest-framework-docs) you can find the demo app(at /demo). It is a project with Django & Django Rest Framework that will allow you to work with this project.
11+
12+
From the root of the repository:
13+
14+
# Create the virtual environment
15+
pyvenv env
16+
17+
# Install requirements
18+
env/bin/pip install -r requirements.txt
19+
20+
# Activate the environment
21+
source env/bin/activate
22+
23+
# Cd Into the demo
24+
cd demo/
25+
26+
# Install Django Rest Framework Docs
27+
pip install -e ../
28+
29+
# Run the project
30+
python manage.py runserver
31+
32+
Note: You do not need a database or to run migrate.
33+
34+
35+
If you are looking to develop this package with one of your **own django projects**:
36+
37+
pyvenv env
38+
env/bin/pip install -r requirements.txt
39+
pip install -e ~/Projects/drf-docs/
40+
41+
### Contributing to the project
42+
43+
1. Fork it!
44+
2. Create your feature branch: `git checkout -b my-new-feature`
45+
3. Commit your changes: `git commit -am 'Add some feature'`
46+
4. Push to the branch: `git push origin my-new-feature`
47+
5. Submit a pull request
48+
6. Make sure tests are passing
49+
50+
51+
### Code of Conduct
52+
53+
As contributors and maintainers of this project, and in the interest of
54+
fostering an open and welcoming community, we pledge to respect all people who
55+
contribute through reporting issues, posting feature requests, updating
56+
documentation, submitting pull requests or patches, and other activities.
57+
58+
We are committed to making participation in this project a harassment-free
59+
experience for everyone, regardless of level of experience, gender, gender
60+
identity and expression, sexual orientation, disability, personal appearance,
61+
body size, race, ethnicity, age, religion, or nationality.
62+
63+
Examples of unacceptable behavior by participants include:
64+
65+
* The use of sexualized language or imagery
66+
* Personal attacks
67+
* Trolling or insulting/derogatory comments
68+
* Public or private harassment
69+
* Publishing other's private information, such as physical or electronic
70+
addresses, without explicit permission
71+
* Other unethical or unprofessional conduct
72+
73+
Project maintainers have the right and responsibility to remove, edit, or
74+
reject comments, commits, code, wiki edits, issues, and other contributions
75+
that are not aligned to this Code of Conduct, or to ban temporarily or
76+
permanently any contributor for other behaviors that they deem inappropriate,
77+
threatening, offensive, or harmful.
78+
79+
By adopting this Code of Conduct, project maintainers commit themselves to
80+
fairly and consistently applying these principles to every aspect of managing
81+
this project. Project maintainers who do not follow or enforce the Code of
82+
Conduct may be permanently removed from the project team.
83+
84+
This Code of Conduct applies both within project spaces and in public spaces
85+
when an individual is representing the project or its community.
86+
87+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
88+
reported by contacting a project maintainer at [email protected]. All
89+
complaints will be reviewed and investigated and will result in a response that
90+
is deemed necessary and appropriate to the circumstances. Maintainers are
91+
obligated to maintain confidentiality with regard to the reporter of an
92+
incident.
93+
94+
95+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
96+
version 1.3.0, available at
97+
[http://contributor-covenant.org/version/1/3/0/][version]
98+
99+
[homepage]: http://contributor-covenant.org
100+
[version]: http://contributor-covenant.org/version/1/3/0/

Diff for: ‎docs/images/django-logo.png

15.5 KB
Loading

Diff for: ‎docs/images/docs.png

298 KB
Loading

Diff for: ‎docs/images/drf-logo.png

35.8 KB
Loading

Diff for: ‎docs/images/live-api.png

458 KB
Loading

Diff for: ‎docs/images/mockup.png

567 KB
Loading

Diff for: ‎docs/index.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: "Home"
3+
permalink: /
4+
order: 1
5+
---
6+
7+
Django REST Framework Docs (DRF Docs) allows you to list all your API Endpoints that inherit from <a href="http://www.django-rest-framework.org/" target="_blank">Django REST Framework</a> **automatically**. Its purpose is to work out of the box and it should take a minimum to install it.
8+
9+
<a class="btn btn-success btn-demo" href="http://demo.drfdocs.com/" target="_blank"><i class="fa fa-laptop"></i> Visit the Demo</a>
10+
11+
12+
#### Live API Endpoints
13+
14+
A really useful feature of DRF Docs is that you can also test endpoints from within the docs. Feel free to use our demo and try them! For more information visit the [Live API Endpoints](/docs/live-api) page of the docs.
15+
16+
<img class="img-responsive" src="images/mockup.png" alt="Mock Up" />
17+
18+
19+
#### How It Works
20+
21+
The concept is pretty simple. Once you [install it](/docs/installation/) you should go the the url you set (ie. `http://0.0.0.0:8000/docs/`) and you should see all your API endpoints along with the serializer fields, allowed methods etc for each one.
22+
23+
DRF Docs will then read all your `urls` and will list those that inherit from Django REST Framework's `APIView`.

Diff for: ‎docs/installation.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: "Installation"
3+
source_filename: "installation"
4+
order: 2
5+
---
6+
7+
The installation itself should not take more than a couple of minutes. Follow the simple steps below.
8+
9+
Install using pip:
10+
11+
pip install drfdocs
12+
13+
Add 'rest_framework_docs' to your `INSTALLED_APPS` setting:
14+
15+
INSTALLED_APPS = (
16+
...
17+
'rest_framework_docs',
18+
)
19+
20+
Finally include the `rest_framework_docs` urls in your `urls.py`:
21+
22+
urlpatterns = [
23+
...
24+
url(r'^docs/', include('rest_framework_docs.urls')),
25+
]
26+
27+
You can now visit [http://0.0.0.0:/8000/docs/](http://0.0.0.0:/8000/docs/) to view your Web API's docs.

Diff for: ‎docs/live-api.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: "Live API Endpoints"
3+
source_filename: "live-api"
4+
order: 5
5+
---
6+
7+
### What is "Live API Endpoints"?
8+
Live API Endpoints allow you to test your endpoints from within DRF docs. For each endpoints you can press the little *plug* icon which will bring up a modal with all the endpoint's fields and all the relevant information so that you can make a request instantly.
9+
10+
It is still in **beta** so if you face any problems - feel free to open an issue/pull request on GitHub.
11+
12+
<img class="img-responsive" src="images/live-api.png" alt="Live API Endpoints" />
13+
14+
The Live API is made with **[React](https://facebook.github.io/react/)**. For more information on how to hack on them, check the README of the repository.

Diff for: ‎docs/settings.md

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: "Settings"
3+
source_filename: "settings"
4+
order: 4
5+
---
6+
7+
### How to set the settings
8+
To set DRF docs' settings just include the dictionary below in Django's `settings.py` file.
9+
10+
REST_FRAMEWORK_DOCS = {
11+
'HIDE_DOCS': True
12+
}
13+
14+
15+
### Settings Description
16+
17+
##### HIDDEN
18+
You can use hidden to prevent your docs from showing up in different environments (ie. Show in development, hide in production). To do so you can use environment variables.
19+
20+
REST_FRAMEWORK_DOCS = {
21+
'HIDE_DOCS': os.environ.get('SHOW_DRFDOCS', False)
22+
}
23+
24+
Then set the value of the environment variable `SHOW_DRFDOCS` for each environment (ie. Use `.env` files)
25+
26+
### List of Settings
27+
28+
{:.table .table-striped}
29+
| Setting | Type | Options | Default |
30+
|---------|---------|-----------------|---------|
31+
|HIDE_DOCS| Boolean | `True`, `False` | `False` |
32+
| | | | |

Diff for: ‎docs/templates.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: "Template Customization"
3+
source_filename: "templates"
4+
order: 6
5+
---
6+
7+
### Create the template file
8+
To edit the template you will have to create a `.html` file to override the original one. Inside your `templates` directory create a directory named `rest_framework_docs` and inside this create the file `docs.html`. You can then extend/override the default template.
9+
10+
{% raw %}
11+
{% extends "rest_framework_docs/base.html" %}
12+
{% endraw %}
13+
14+
15+
### Default Blocks
16+
17+
18+
#### Styles (CSS)
19+
20+
{% raw %}
21+
{% block style %}
22+
<link rel="stylesheet" href="{% static "path/to/custom/css/style.css" %}">
23+
{% endblock %}
24+
{% endraw %}
25+
26+
#### GitHub Badge
27+
To hide the GitHub badge from the page, just override it with an empty block.
28+
29+
{% raw %}{% block github_badge %}{% endblock %}{% endraw %}
30+
31+
#### Title
32+
33+
{% raw %}{% block title %}Project Name{% endblock %}{% endraw %}
34+
35+
#### Logo
36+
37+
{% raw %}
38+
{% block logo %}
39+
<a class="navbar-brand" href="http://www.drfdocs.com/">DRF Docs</a>
40+
{% endblock %}
41+
{% endraw %}
42+
43+
#### Jumbotron
44+
45+
{% raw %}
46+
{% block jumbotron %}
47+
<div class="jumbotron">
48+
<h1>Project Title</h1>
49+
<h3>Documentantion of the project 'Example'.</h3>
50+
</div>
51+
{% endblock %}
52+
{% endraw %}
53+
54+
#### Footer
55+
56+
{% raw %}
57+
{% block footer %}
58+
<div class="footer">
59+
<div class="links">
60+
<a href="http://www.iamemmanouil.com"><i class="fa fa-link"></i></a>
61+
<a href="http://www.github.com/ekonstantinidis"><i class="fa fa-github"></i></a>
62+
<a href="http://www.twitter.com/iamemmanouil"><i class="fa fa-twitter"></i></a>
63+
</div>
64+
Copyright © 2015 Emmanouil Konstantinidis.
65+
</div>
66+
{% endblock %}
67+
{% endraw %}
68+
69+
70+
### Complete Example
71+
File location: `templates/rest_framework_docs/docs.html`
72+
73+
{% raw %}
74+
{% extends "rest_framework_docs/base.html" %}
75+
76+
{% block title %}Project Name{% endblock %}
77+
{% block logo %}<a class="navbar-brand" href="#"">Project Name API Documentation</a>{% endblock %}
78+
79+
{% block jumbotron %}
80+
<div class="jumbotron">
81+
<h1>'Project Name' Web API</h1>
82+
<h3>Documentantion of the 'Project Name' Web API.</h3>
83+
</div>
84+
{% endblock %}
85+
86+
{% block footer %}<div class="footer">Copyright © 2015 Project Name.</div>{% endblock %}
87+
88+
{% endraw %}

Diff for: ‎mkdocs.yml

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
site_name: DRF Docs
2+
3+
pages:
4+
- Home: index.md
5+
- Changelog: changelog.md
6+
- Contributing: contributing.md
7+
- Installation: installation.md
8+
- Live API Endpoints: live-api.md
9+
- Settings: settings.md
10+
- Templates: templates.md
11+
12+
theme: flatly

Diff for: ‎requirements.txt

+1
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ Django==1.8.7
22
djangorestframework==3.3.2
33
coverage==4.0.3
44
flake8==2.5.1
5+
mkdocs==0.15.3

0 commit comments

Comments
 (0)