Skip to content

Commit 7c88388

Browse files
MiltonLnMiltonLn
committed
Docs finished.
1 parent f2f6b97 commit 7c88388

21 files changed

+801
-16
lines changed

‎README.rst

+5-5
Original file line numberDiff line numberDiff line change
@@ -31,14 +31,14 @@ Installation:
3131

3232
You can install it with one of these options:
3333

34-
- easy\_install django-menu-generator
35-
- pip install django-menu-generator
36-
- git clone https://github.com/RADYConsultores/django-menu-generator
34+
- ``easy_install django-menu-generator``
35+
- ``pip install django-menu-generator``
36+
- ``git clone https://github.com/RADYConsultores/django-menu-generator``
3737

38-
1. cd django-menu-generator
38+
1. ``cd django-menu-generator``
3939
2. run python setup.py
4040

41-
- wget https://github.com/RADYConsultores/django-menu-generator/zipball/master
41+
- ``wget https://github.com/RADYConsultores/django-menu-generator/zipball/master``
4242

4343
1. unzip the downloaded file
4444
2. cd into django-menu-generator-\* directory

‎docs/_build_html/.doctrees/changelog.doctree

1.81 KB
Binary file not shown.

‎docs/_build_html/.doctrees/environment.pickle

3.59 KB
Binary file not shown.

‎docs/_build_html/.doctrees/menugeneration.doctree

17.5 KB
Binary file not shown.

‎docs/_build_html/.doctrees/urls.doctree

5.41 KB
Binary file not shown.

‎docs/_build_html/.doctrees/validators.doctree

21.6 KB
Binary file not shown.

‎docs/_build_html/_sources/changelog.rst.txt

+14
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,16 @@
11
CHANGELOG
22
=========
3+
4+
1.0.1(2017-04-29)
5+
-----------------
6+
7+
- Added docs
8+
- Readme enhanced
9+
- BUGFIX: Added a correction to the validators evaluation with the AND connector
10+
- Added flake8 to CI
11+
- Added tox
12+
13+
1.0.0 (2017-04-09)
14+
------------------
15+
16+
- Initial release

‎docs/_build_html/_sources/menugeneration.rst.txt

+84
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,86 @@
11
Menu Generation
22
===============
3+
4+
Django Menu Generator uses python dictionaries to represent the menu items, usually a menu item is as follows:
5+
6+
.. code:: python
7+
8+
{
9+
"name": 'some name',
10+
"icon_class": 'some icon class',
11+
"url": URL spec,
12+
"validators": [ list of validators ],
13+
"submenu": Dictionary like this
14+
}
15+
16+
Where each key is as follows:
17+
18+
- ``name``: A string representing the label of the menu item. If you are using i18n here you can pass the name with the ``ugettext_lazy`` function
19+
20+
- ``icon_class``: A string representing the class of the icon you wish to show on the menu item, e.g you can use font-awesome
21+
22+
- ``url``: See :doc:`urls`
23+
24+
- ``validators``: See :doc:`validators`
25+
26+
- ``submenu``: You can create infinite nested submenus passing here menu items like this
27+
28+
Django Menu Generator offers two ways to generate the menus, through the Django settings and through each of the Django
29+
apps
30+
31+
Generating menus through settings
32+
---------------------------------
33+
34+
You can add various list dictionaries representing each menu you have as explained in :doc:`usage`
35+
We recommend to have a ``menus.py`` file with the menu list dictionaries and then import it to the settings file if you
36+
go this way
37+
38+
Generating menus through apps
39+
-----------------------------
40+
41+
Some people prefer to isolate all the aspects of a project between apps, so, we add this feature to allow the menus
42+
live inside each app.
43+
44+
You need to add inside the app a ``menus.py`` file that contains a dictionary called ``MENUS``, each element of the
45+
dictionary will be a menu list dictionary with all the configuration needed to display that menu, e.g:
46+
47+
.. code:: python
48+
49+
MENUS = {
50+
'NAV_MENU_LEFT': [
51+
{
52+
"name": "App1 Feature",
53+
"url": "/app1-feature"
54+
}
55+
],
56+
'NAV_MENU_TOP': [
57+
{
58+
"name": "Second Menu Feature",
59+
"url": "named_url"
60+
}
61+
]
62+
}
63+
64+
So, as an example, for the ``'NAV_MENU_LEFT'``, Django Menu Generator will loop each app searching for the ``'NAV_MENU_LEFT'``
65+
list dictionaries inside of the ``MENUS`` and build all the menu configuration to build the whole menu.
66+
67+
With this feature you can have a project structure like this::
68+
69+
your_project/
70+
├── config_folder/
71+
│ └── ...
72+
├── app1
73+
│ └── models.py
74+
│ forms.py
75+
│ views.py
76+
│ menus.py
77+
│
78+
├── app2
79+
│ └── models.py
80+
│ forms.py
81+
│ views.py
82+
│ menus.py
83+
│
84+
...
85+
86+
You can have a mix of the two approaches if you wish

‎docs/_build_html/_sources/urls.rst.txt

+38
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,40 @@
11
URLs
22
====
3+
4+
You can pass the URL parameters to menu items in three ways.
5+
6+
Raw URLs
7+
--------
8+
9+
A hard-coded url:
10+
11+
.. code:: python
12+
13+
"url": '/some-path/to-feature'
14+
15+
Reversible URLs
16+
---------------
17+
18+
An url that can be reversed with the `reverse` method:
19+
20+
.. code:: python
21+
22+
"url": 'named_url'
23+
24+
URL with args or kwargs
25+
-----------------------
26+
27+
e.g. If you have an url with kwargs like this:
28+
29+
.. code:: python
30+
31+
url(r'^update/(?P<pk>\d+)/$', SomeView.as_view(), name='update'),
32+
33+
you can pass the url as follows:
34+
35+
"url": {"viewname": 'update', "kwargs": {"pk": 1}}
36+
37+
In fact, you can pass any of the parameters of the reverse method through the dictionary
38+
39+
For Django 1.10 the reverse method sign is: ``reverse(viewname, urlconf=None, args=None, kwargs=None, current_app=None)``
40+

‎docs/_build_html/_sources/validators.rst.txt

+121
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,123 @@
11
Validators
22
==========
3+
4+
Django Menu Generator uses validators to allow the displaying of menu items.
5+
6+
A validator is a function that receives the request as arg and returns a boolean indicating if the check has passed
7+
8+
for Django Menu Generator the validators must always be a list containing at least one callable or python path to a callable.
9+
If there is more than one validator, all of them will be evaluated using the AND connector.
10+
11+
Built-in validators
12+
-------------------
13+
14+
Django Menu Generator has the following built-in validators:
15+
16+
- is_superuser:
17+
18+
A validator to check if the authenticated user is a superuser
19+
20+
Usage:
21+
22+
.. code:: python
23+
24+
"validators": ['menu_generator.validators.is_superuser']
25+
26+
- is_staff:
27+
28+
A validator to check if the authenticated user is member of the staff
29+
30+
Usage:
31+
32+
.. code:: python
33+
34+
"validators": ['menu_generator.validators.is_staff']
35+
36+
- is_authenticated:
37+
38+
A validator to check if user is authenticated
39+
40+
Usage:
41+
42+
.. code:: python
43+
44+
"validators": ['menu_generator.validators.is_authenticated']
45+
46+
- is_anonymous:
47+
48+
A validator to check if the user is not authenticated
49+
50+
Usage:
51+
52+
.. code:: python
53+
54+
"validators": ['menu_generator.validators.is_anonymous']
55+
56+
- user_has_permission:
57+
58+
A validator to check if the user has the given permission
59+
60+
Usage:
61+
62+
.. code:: python
63+
64+
"validators": [
65+
('menu_generator.validators.user_has_permission', 'app_label.permission_codename')
66+
]
67+
68+
- More than one validator:
69+
70+
You can pass more than one validator to evaluate using the AND connector
71+
72+
.. code:: python
73+
74+
"validators": [
75+
'menu_generator.validators.is_staff',
76+
('menu_generator.validators.user_has_permission', 'some_app.some_permission')
77+
...
78+
]
79+
80+
Custom validators
81+
-----------------
82+
83+
You can build your own validators and use them with Django Menu Generator
84+
85+
Let's build a validator that checks if the user have more than one pet (dummy example) assuming the user has a
86+
many to many relation called pets
87+
88+
Assuming we build the function inside ``your_project/app1`` on a ``menu_validators.py`` we have:
89+
90+
.. code:: python
91+
92+
# Remember you always must to past the request as first parameter
93+
def has_more_than_one_pet(request):
94+
95+
return request.user.pets.count() > 0
96+
97+
So we can use it as a validator
98+
99+
.. code:: python
100+
101+
"validators": ['your_project.app1.menu_validators.has_more_than_one_pet']
102+
103+
Now let's build a validator that checks if the user's pet belongs to a specific type to illustrate the validators with
104+
parameters.
105+
106+
Assuming we build the function inside the same path and the user have a foreign key called pet
107+
108+
.. code:: python
109+
110+
def has_a_pet_of_type(request, type):
111+
112+
return request.user.pet.type == type
113+
114+
So we use the validator like this:
115+
116+
.. code:: python
117+
118+
"validators": [
119+
('your_project.app1.menu_validators.has_a_pet_of_type', 'DOG')
120+
]
121+
122+
As you can see, we use tuples to pass parameters to the validators, where the first position is the validator and the rest are
123+
the function parameters

‎docs/_build_html/changelog.html

+26-1
Original file line numberDiff line numberDiff line change
@@ -45,14 +45,39 @@
4545

4646
<div class="section" id="changelog">
4747
<h1>CHANGELOG<a class="headerlink" href="#changelog" title="Permalink to this headline"></a></h1>
48+
<div class="section" id="id1">
49+
<h2>1.0.1(2017-04-29)<a class="headerlink" href="#id1" title="Permalink to this headline"></a></h2>
50+
<ul class="simple">
51+
<li>Added docs</li>
52+
<li>Readme enhanced</li>
53+
<li>BUGFIX: Added a correction to the validators evaluation with the AND connector</li>
54+
<li>Added flake8 to CI</li>
55+
<li>Added tox</li>
56+
</ul>
57+
</div>
58+
<div class="section" id="id2">
59+
<h2>1.0.0 (2017-04-09)<a class="headerlink" href="#id2" title="Permalink to this headline"></a></h2>
60+
<ul class="simple">
61+
<li>Initial release</li>
62+
</ul>
63+
</div>
4864
</div>
4965

5066

5167
</div>
5268
</div>
5369
</div>
5470
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
55-
<div class="sphinxsidebarwrapper"><div class="relations">
71+
<div class="sphinxsidebarwrapper">
72+
<h3><a href="index.html">Table Of Contents</a></h3>
73+
<ul>
74+
<li><a class="reference internal" href="#">CHANGELOG</a><ul>
75+
<li><a class="reference internal" href="#id1">1.0.1(2017-04-29)</a></li>
76+
<li><a class="reference internal" href="#id2">1.0.0 (2017-04-09)</a></li>
77+
</ul>
78+
</li>
79+
</ul>
80+
<div class="relations">
5681
<h3>Related Topics</h3>
5782
<ul>
5883
<li><a href="index.html">Documentation overview</a><ul>

‎docs/_build_html/index.html

+21-4
Original file line numberDiff line numberDiff line change
@@ -66,10 +66,27 @@ <h2>Contents:<a class="headerlink" href="#contents" title="Permalink to this hea
6666
<ul>
6767
<li class="toctree-l1"><a class="reference internal" href="install.html">Installation</a></li>
6868
<li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a></li>
69-
<li class="toctree-l1"><a class="reference internal" href="menugeneration.html">Menu Generation</a></li>
70-
<li class="toctree-l1"><a class="reference internal" href="urls.html">URLs</a></li>
71-
<li class="toctree-l1"><a class="reference internal" href="validators.html">Validators</a></li>
72-
<li class="toctree-l1"><a class="reference internal" href="changelog.html">CHANGELOG</a></li>
69+
<li class="toctree-l1"><a class="reference internal" href="menugeneration.html">Menu Generation</a><ul>
70+
<li class="toctree-l2"><a class="reference internal" href="menugeneration.html#generating-menus-through-settings">Generating menus through settings</a></li>
71+
<li class="toctree-l2"><a class="reference internal" href="menugeneration.html#generating-menus-through-apps">Generating menus through apps</a></li>
72+
</ul>
73+
</li>
74+
<li class="toctree-l1"><a class="reference internal" href="urls.html">URLs</a><ul>
75+
<li class="toctree-l2"><a class="reference internal" href="urls.html#raw-urls">Raw URLs</a></li>
76+
<li class="toctree-l2"><a class="reference internal" href="urls.html#reversible-urls">Reversible URLs</a></li>
77+
<li class="toctree-l2"><a class="reference internal" href="urls.html#url-with-args-or-kwargs">URL with args or kwargs</a></li>
78+
</ul>
79+
</li>
80+
<li class="toctree-l1"><a class="reference internal" href="validators.html">Validators</a><ul>
81+
<li class="toctree-l2"><a class="reference internal" href="validators.html#built-in-validators">Built-in validators</a></li>
82+
<li class="toctree-l2"><a class="reference internal" href="validators.html#custom-validators">Custom validators</a></li>
83+
</ul>
84+
</li>
85+
<li class="toctree-l1"><a class="reference internal" href="changelog.html">CHANGELOG</a><ul>
86+
<li class="toctree-l2"><a class="reference internal" href="changelog.html#id1">1.0.1(2017-04-29)</a></li>
87+
<li class="toctree-l2"><a class="reference internal" href="changelog.html#id2">1.0.0 (2017-04-09)</a></li>
88+
</ul>
89+
</li>
7390
<li class="toctree-l1"><a class="reference internal" href="tests.html">Running the tests</a></li>
7491
<li class="toctree-l1"><a class="reference internal" href="contribute.html">Contribute</a></li>
7592
<li class="toctree-l1"><a class="reference internal" href="support.html">Support</a></li>

0 commit comments

Comments
 (0)