Skip to content

Commit 1edde83

Browse files
author
Mauricio Collazos
committed
added first version of docs
1 parent 5e93ddb commit 1edde83

File tree

5 files changed

+381
-0
lines changed

5 files changed

+381
-0
lines changed

docs/Makefile

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SOURCEDIR = source
8+
BUILDDIR = build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Configuration file for the Sphinx documentation builder.
4+
#
5+
# This file does only contain a selection of the most common options. For a
6+
# full list see the documentation:
7+
# http://www.sphinx-doc.org/en/master/config
8+
9+
# -- Path setup --------------------------------------------------------------
10+
11+
# If extensions (or modules to document with autodoc) are in another directory,
12+
# add these directories to sys.path here. If the directory is relative to the
13+
# documentation root, use os.path.abspath to make it absolute, like shown here.
14+
#
15+
# import os
16+
# import sys
17+
# sys.path.insert(0, os.path.abspath('.'))
18+
19+
20+
# -- Project information -----------------------------------------------------
21+
22+
project = u'Django Crud Generator'
23+
copyright = u'2018, contraslash S.A.S.'
24+
author = u'contraslash S.A.S.'
25+
26+
# The short X.Y version
27+
version = u''
28+
# The full version, including alpha/beta/rc tags
29+
release = u'0.3.1'
30+
31+
32+
# -- General configuration ---------------------------------------------------
33+
34+
# If your documentation needs a minimal Sphinx version, state it here.
35+
#
36+
# needs_sphinx = '1.0'
37+
38+
# Add any Sphinx extension module names here, as strings. They can be
39+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
40+
# ones.
41+
extensions = [
42+
]
43+
44+
# Add any paths that contain templates here, relative to this directory.
45+
templates_path = ['_templates']
46+
47+
# The suffix(es) of source filenames.
48+
# You can specify multiple suffix as a list of string:
49+
from recommonmark.parser import CommonMarkParser
50+
51+
source_parsers = {
52+
'.md': CommonMarkParser,
53+
}
54+
55+
source_suffix = ['.rst', '.md']
56+
# source_suffix = '.rst'
57+
58+
# The master toctree document.
59+
master_doc = 'index'
60+
61+
# The language for content autogenerated by Sphinx. Refer to documentation
62+
# for a list of supported languages.
63+
#
64+
# This is also used if you do content translation via gettext catalogs.
65+
# Usually you set "language" from the command line for these cases.
66+
language = None
67+
68+
# List of patterns, relative to source directory, that match files and
69+
# directories to ignore when looking for source files.
70+
# This pattern also affects html_static_path and html_extra_path.
71+
exclude_patterns = []
72+
73+
# The name of the Pygments (syntax highlighting) style to use.
74+
pygments_style = None
75+
76+
77+
# -- Options for HTML output -------------------------------------------------
78+
79+
# The theme to use for HTML and HTML Help pages. See the documentation for
80+
# a list of builtin themes.
81+
#
82+
html_theme = 'sphinx_rtd_theme'
83+
84+
# Theme options are theme-specific and customize the look and feel of a theme
85+
# further. For a list of options available for each theme, see the
86+
# documentation.
87+
#
88+
# html_theme_options = {}
89+
90+
# Add any paths that contain custom static files (such as style sheets) here,
91+
# relative to this directory. They are copied after the builtin static files,
92+
# so a file named "default.css" will overwrite the builtin "default.css".
93+
html_static_path = ['_static']
94+
95+
# Custom sidebar templates, must be a dictionary that maps document names
96+
# to template names.
97+
#
98+
# The default sidebars (for documents that don't match any pattern) are
99+
# defined by theme itself. Builtin themes are using these templates by
100+
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
101+
# 'searchbox.html']``.
102+
#
103+
# html_sidebars = {}
104+
105+
106+
# -- Options for HTMLHelp output ---------------------------------------------
107+
108+
# Output file base name for HTML help builder.
109+
htmlhelp_basename = 'DjangoCrudGeneratordoc'
110+
111+
112+
# -- Options for LaTeX output ------------------------------------------------
113+
114+
latex_elements = {
115+
# The paper size ('letterpaper' or 'a4paper').
116+
#
117+
# 'papersize': 'letterpaper',
118+
119+
# The font size ('10pt', '11pt' or '12pt').
120+
#
121+
# 'pointsize': '10pt',
122+
123+
# Additional stuff for the LaTeX preamble.
124+
#
125+
# 'preamble': '',
126+
127+
# Latex figure (float) alignment
128+
#
129+
# 'figure_align': 'htbp',
130+
}
131+
132+
# Grouping the document tree into LaTeX files. List of tuples
133+
# (source start file, target name, title,
134+
# author, documentclass [howto, manual, or own class]).
135+
latex_documents = [
136+
(master_doc, 'DjangoCrudGenerator.tex', u'Django Crud Generator Documentation',
137+
u'contraslash S.A.S.', 'manual'),
138+
]
139+
140+
141+
# -- Options for manual page output ------------------------------------------
142+
143+
# One entry per manual page. List of tuples
144+
# (source start file, name, description, authors, manual section).
145+
man_pages = [
146+
(master_doc, 'djangocrudgenerator', u'Django Crud Generator Documentation',
147+
[author], 1)
148+
]
149+
150+
151+
# -- Options for Texinfo output ----------------------------------------------
152+
153+
# Grouping the document tree into Texinfo files. List of tuples
154+
# (source start file, target name, title, author,
155+
# dir menu entry, description, category)
156+
texinfo_documents = [
157+
(master_doc, 'DjangoCrudGenerator', u'Django Crud Generator Documentation',
158+
author, 'DjangoCrudGenerator', 'One line description of project.',
159+
'Miscellaneous'),
160+
]
161+
162+
163+
# -- Options for Epub output -------------------------------------------------
164+
165+
# Bibliographic Dublin Core info.
166+
epub_title = project
167+
168+
# The unique identifier of the text. This can be a ISBN number
169+
# or the project homepage.
170+
#
171+
# epub_identifier = ''
172+
173+
# A unique identification for the text.
174+
#
175+
# epub_uid = ''
176+
177+
# A list of files that should not be packed into the epub file.
178+
epub_exclude_files = ['search.html']
Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Create a blog in 5 Minutes
2+
3+
We present a set of instructions in form of scripts, you can copy and paste the full section, but we recommend to execute every single command and understand what it does
4+
```bash
5+
# Create a folder for the project
6+
mkdir myblog
7+
# Enter the folder
8+
cd myblog
9+
# Create a new virtualenv
10+
python -m venv virtualenv
11+
# Activate the environment
12+
source virtualenv/bin/activate
13+
# First install django
14+
pip install django
15+
# Then create a project
16+
django-admin startproject myblog .
17+
# Y really like to have all applications in an applications folder
18+
mkdir applications && touch applications/__init__.py
19+
# Install django crud generator
20+
pip install django-crud-generator
21+
# Get a copy of base-django
22+
git clone https://github.com/contraslash/base-django base
23+
# enter the application folder
24+
cd applications
25+
# Get a base template
26+
git clone https://github.com/contraslash/template_cdn_bootstrap
27+
# Get an authentication module
28+
git clone https://github.com/contraslash/authentication-django authentication
29+
# Create your blog application
30+
django-admin startapp blog
31+
# Go back to root of project
32+
cd ..
33+
```
34+
35+
Now you have the shell of an app, you need to write the core.
36+
37+
First create your post model, in order to do so put this content on your `applications/blog/models.py`
38+
39+
```python
40+
from django.db import models
41+
from django.contrib.auth import models as auth_models
42+
43+
from base import models as base_models
44+
45+
from . import (
46+
conf
47+
)
48+
49+
50+
class Post(base_models.FullSlugBaseModel):
51+
author = models.ForeignKey(auth_models.User, on_delete=models.CASCADE)
52+
53+
url_name = conf.POST_DETAIL_URL_NAME
54+
```
55+
56+
Now we create the scaffold for `Post` model using django-crud-generator
57+
58+
```bash
59+
django-crud-generator.py --model_name Post --django_application_folder applications/blog/ --slug
60+
```
61+
62+
Now we must edit our `myblog/settings.py` file and at the end of the file
63+
64+
```python
65+
# Append the new apps to the `INSTALLED_APPS`
66+
INSTALLED_APPS += [
67+
68+
# Contraslash Apps
69+
'base',
70+
'applications.authentication',
71+
'applications.template_cdn_bootstrap',
72+
73+
# Custom apps
74+
'applications.blog'
75+
]
76+
77+
# And define an the LOGIN URL
78+
LOGIN_URL = "log_in"
79+
```
80+
81+
And include the configuration for the `myblog/urls.py`
82+
83+
```python
84+
from django.contrib import admin
85+
from django.urls import path, include
86+
87+
urlpatterns = [
88+
path('admin/', admin.site.urls),
89+
path(
90+
'authentication/',
91+
include(
92+
"applications.authentication.urls",
93+
)
94+
),
95+
path(
96+
'',
97+
include(
98+
"applications.blog.urls",
99+
)
100+
),
101+
]
102+
```
103+
104+
Now we're ready to run the `manage.py` command.
105+
106+
```bash
107+
# First create the new migrations
108+
python manage.py makemigrations
109+
# Migrate the schemas to the database
110+
python manage.py migrate
111+
# And create a superuser
112+
python manage.py createsuperuser
113+
# Now run the server
114+
python manage.py runserver
115+
```
116+
117+
Now be free to modify the template of the list and detail of your post

docs/source/getting_started.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Getting Started
2+
3+
Django Crud Generator is not intended to create a django application from the scratch, in the opposite way just scaffold
4+
a new structure to create basic operations based on [base-django](https://github.com/contraslash/base-django) package.
5+
6+
This package must be installed in the root of your project with the name base. To do so:
7+
8+
```bash
9+
git clone https://github.com/contraslash/base-django base
10+
```
11+
12+
> If you want to create a site from scratch please check our [create a blog in 5]()
13+
14+
To use [django-crud-generator](https://pypi.org/project/django-crud-generator/), first install the latest version from pip
15+
16+
```bash
17+
pip install django-crud-generator
18+
```
19+
20+
21+
Now assume you have a `Post` Model under an app called `blog`, to create the structure use
22+
23+
```bash
24+
django-crud-generator.py --django_application_folder blog --model_name Post
25+
```
26+
27+
Now you can add the `urls.py` file to your main tree.
28+
29+
To fully customize your templates, add `template_name` attribute to each class.
30+
31+
By default django-crud-generator asumes you already have a `base.html` template, like in all common django sites, with
32+
the default schema
33+
34+
```html
35+
<html>
36+
<head>
37+
</head>
38+
<body>
39+
{% block content %}
40+
41+
{% endblock %}
42+
</body>
43+
</html>
44+
```

docs/source/index.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. Django Crud Generator documentation master file, created by
2+
sphinx-quickstart on Fri Sep 14 14:13:12 2018.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to Django Crud Generator's documentation!
7+
=================================================
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
:caption: Contents:
12+
13+
getting_started.md
14+
create_blog_in_5_minutes.md
15+
16+
17+
18+
Indices and tables
19+
==================
20+
21+
* :ref:`genindex`
22+
* :ref:`modindex`
23+
* :ref:`search`

0 commit comments

Comments
 (0)