ravenscroftj
/
django-project-structure
mirror of https://github.com/saqibur/django-project-structure.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: rebuild site based on latest readme

This commit is contained in:
Saqibur Rahman 2024-11-05 15:36:20 +06:00
parent 0187b89906
commit 9814b32116
7 changed files with 550 additions and 444 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -215,3 +215,9 @@ defaults, but let's hope we have time to work on it on the `cookiecutter` branch
- [Build APIs You Won't Hate](https://apisyouwonthate.com/books/build-apis-you-wont-hate/) - [Build APIs You Won't Hate](https://apisyouwonthate.com/books/build-apis-you-wont-hate/)
- [Tuxedo Style Guides](https://github.com/saqibur/tuxedo) - [Tuxedo Style Guides](https://github.com/saqibur/tuxedo)
- [Django Anti Patterns](https://www.django-antipatterns.com/) - [Django Anti Patterns](https://www.django-antipatterns.com/)
## Documentation
* Copy README.md to `mkdocs` folder
* Build: `mkdocs build -d docs`
* Serve: `mkdocs serve`

6
docs/404.html
View File

@ -6,7 +6,7 @@
<meta charset="utf-8"> <meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1"> <meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="This is a template/project structure for developing django-based applications - either strictly through the django-rest-framework or just django."> <meta name="description" content="This is a template/project structure for developing django-based applications - using django-rest-framework along with django.">
<meta name="author" content="Saqibur Rahman"> <meta name="author" content="Saqibur Rahman">
@ -16,7 +16,7 @@
<link rel="icon" href="/saqibur/django-project-structure/assets/images/favicon.png"> <link rel="icon" href="/saqibur/django-project-structure/assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.5.3, mkdocs-material-9.4.12"> <meta name="generator" content="mkdocs-1.6.0, mkdocs-material-9.4.12">
@ -275,7 +275,7 @@
<div class="md-copyright"> <div class="md-copyright">
<div class="md-copyright__highlight"> <div class="md-copyright__highlight">
Copyright &copy; 2022 - 2023 Saqibur Rahman Copyright &copy; 2022 - 2024 Saqibur Rahman
</div> </div>

142
docs/index.html
View File

@ -6,7 +6,7 @@
<meta charset="utf-8"> <meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1"> <meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="This is a template/project structure for developing django-based applications - either strictly through the django-rest-framework or just django."> <meta name="description" content="This is a template/project structure for developing django-based applications - using django-rest-framework along with django.">
<meta name="author" content="Saqibur Rahman"> <meta name="author" content="Saqibur Rahman">
@ -18,7 +18,7 @@
<link rel="icon" href="assets/images/favicon.png"> <link rel="icon" href="assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.5.3, mkdocs-material-9.4.12"> <meta name="generator" content="mkdocs-1.6.0, mkdocs-material-9.4.12">
@ -269,6 +269,15 @@
</label> </label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#some-batteries-included" class="md-nav__link">
<span class="md-ellipsis">
Some batteries included:
</span>
</a>
</li>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#getting-started" class="md-nav__link"> <a href="#getting-started" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
@ -393,6 +402,15 @@
</ul> </ul>
</nav> </nav>
</li>
<li class="md-nav__item">
<a href="#faq" class="md-nav__link">
<span class="md-ellipsis">
FAQ
</span>
</a>
</li> </li>
<li class="md-nav__item"> <li class="md-nav__item">
@ -438,6 +456,15 @@
</label> </label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#some-batteries-included" class="md-nav__link">
<span class="md-ellipsis">
Some batteries included:
</span>
</a>
</li>
<li class="md-nav__item"> <li class="md-nav__item">
<a href="#getting-started" class="md-nav__link"> <a href="#getting-started" class="md-nav__link">
<span class="md-ellipsis"> <span class="md-ellipsis">
@ -562,6 +589,15 @@
</ul> </ul>
</nav> </nav>
</li>
<li class="md-nav__item">
<a href="#faq" class="md-nav__link">
<span class="md-ellipsis">
FAQ
</span>
</a>
</li> </li>
<li class="md-nav__item"> <li class="md-nav__item">
@ -591,19 +627,27 @@
<p><a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg" /></a> <p><a href="https://www.python.org/downloads/release/python-3123/"><img alt="Python 3.12.3" src="https://img.shields.io/badge/python-3.12.3-blue.svg" /></a>
<a href="https://www.python.org/downloads/release/python-3108//"><img alt="Python 3.10.8" src="https://img.shields.io/badge/python-3.10.8-blue.svg" /></a> <a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" /></a>
<a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" /></a></p> <a href="https://pre-commit.com/"><img alt="Pre-commit" src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&amp;logoColor=white" /></a></p>
<p><img alt="Django" src="https://img.shields.io/badge/django-%23092E20.svg?style=for-the-badge&amp;logo=django&amp;logoColor=white" /> <p><img alt="Django" src="https://img.shields.io/badge/django-%23092E20.svg?style=for-the-badge&amp;logo=django&amp;logoColor=white" />
<img alt="DjangoREST" src="https://img.shields.io/badge/DJANGO-REST-ff1709?style=for-the-badge&amp;logo=django&amp;logoColor=white&amp;color=ff1709&amp;labelColor=gray" /> <img alt="DjangoREST" src="https://img.shields.io/badge/DJANGO-REST-ff1709?style=for-the-badge&amp;logo=django&amp;logoColor=white&amp;color=ff1709&amp;labelColor=gray" />
<img alt="Postgres" src="https://img.shields.io/badge/postgres-%23316192.svg?style=for-the-badge&amp;logo=postgresql&amp;logoColor=white" /> <img alt="Postgres" src="https://img.shields.io/badge/postgres-%23316192.svg?style=for-the-badge&amp;logo=postgresql&amp;logoColor=white" />
<img alt="Swagger" src="https://img.shields.io/badge/-Swagger-%23Clojure?style=for-the-badge&amp;logo=swagger&amp;logoColor=white" /></p> <img alt="Swagger" src="https://img.shields.io/badge/-Swagger-%23Clojure?style=for-the-badge&amp;logo=swagger&amp;logoColor=white" /></p>
<h1 id="django-project-structure">Django Project Structure</h1> <h1 id="django-project-structure">Django Project Structure</h1>
<p>This is a template/project structure for developing django-based applications - <p>This is a template/project structure for developing django-based applications -
either strictly through the <code>django-rest-framework</code> or just <code>django</code>.</p> using <code>django-rest-framework</code> along with <code>django</code>.</p>
<p>The project is meant to be easily clone-able, and used as the starter template <p>The project is meant to be easily clone-able, and used as the starter template
for the next big thing you develop. Note, this is a folder structure only, not for the next big thing you develop. Note, this is a folder structure only, not
“best practices”.</p> “best practices”.</p>
<h2 id="some-batteries-included">Some batteries included:</h2>
<ul>
<li><a href="https://django-storages.readthedocs.io/en/stable/">Django Storages</a> - To integrate with different types of storages</li>
<li><a href="https://www.django-rest-framework.org/">Django Rest Framework</a> - For API development</li>
<li><a href="https://github.com/adamchainz/django-cors-headers">Django CORS Headers</a> - To allow requests from other origins</li>
<li><a href="https://docs.sentry.io/platforms/python/">Sentry</a> - For crashes</li>
<li><a href="https://gunicorn.org/">Gunicorn</a> - As a web server</li>
</ul>
<h2 id="getting-started">Getting Started</h2> <h2 id="getting-started">Getting Started</h2>
<ol> <ol>
<li>Since this is a template repository, simply hit "Use this template" on GitHub <li>Since this is a template repository, simply hit "Use this template" on GitHub
@ -612,7 +656,18 @@ anything you see fit.</li>
<li>Run the project using <code>python manage.py runserver</code> and you should see the <li>Run the project using <code>python manage.py runserver</code> and you should see the
default success page provided by Django at default success page provided by Django at
<a href="http://127.0.0.1:8000/">http://127.0.0.1:8000/</a>.</li> <a href="http://127.0.0.1:8000/">http://127.0.0.1:8000/</a>.</li>
<li>[Optional] If you want to configure database, in the <code>DATABASE</code> section of
<code>settings.py</code> we have added <code>postgresql</code> as the default <code>DATABASE</code> (As most of
the application are using it). You can roll back to the <code>sqlite</code> by adding the
following code snippet, removing the current one.</li>
</ol> </ol>
<pre><code class="language-bash">DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
}
}
</code></pre>
<h3 id="creating-an-app">Creating an App</h3> <h3 id="creating-an-app">Creating an App</h3>
<ol> <ol>
<li>Create a folder with the app name in <code>apps</code>. For example: <code>poll</code></li> <li>Create a folder with the app name in <code>apps</code>. For example: <code>poll</code></li>
@ -621,60 +676,59 @@ project</li>
</ol> </ol>
<h2 id="project-tree">Project Tree</h2> <h2 id="project-tree">Project Tree</h2>
<pre><code class="language-bash">. <pre><code class="language-bash">.
├── apps ├── apps/
│ └── example # A django rest app │ └── example/ # A django rest app
│ ├── api │ ├── api/
│ │ ├── v1 # Only the &quot;presentation&quot; layer exists here. │ │ ├── v1/ # Only the &quot;presentation&quot; layer exists here.
│ │ │ ├── __init__.py │ │ │ ├── __init__.py
│ │ │ ├── serializers.py │ │ │ ├── serializers.py
│ │ │ ├── urls.py │ │ │ ├── urls.py
│ │ │ └── views.py │ │ │ └── views.py
│ │ ├── v2 # Only the &quot;presentation&quot; layer exists here. │ │ ├── v2 # Only the &quot;presentation&quot; layer exists here.
│ │ │ ├── __init__.py │ │ │ ├── __init__.py
│ │ │ ├── serializers.py │ │ │ ├── serializers.py
│ │ │ ├── urls.py │ │ │ ├── urls.py
│ │ │ └── views.py │ │ │ └── views.py
│ │ └── __init__.py │ │ └── __init__.py
│ ├── fixtures # Constant &quot;seeders&quot; to populate your database │ ├── fixtures/ # Constant &quot;seeders&quot; to populate your database
│ ├── management │ ├── management/
│ │ ├── commands # Try and write some database seeders here │ │ ├── commands/ # Try and write some database seeders here
│ │ │ └── command.py │ │ │ └── command.py
│ │ └── __init__.py │ │ └── __init__.py
│ ├── migrations │ ├── migrations/
│ │ └── __init__.py │ │ └── __init__.py
│ ├── templates # App-specific templates go here │ ├── templates/ # App-specific templates go here
│ ├── tests # All your integration and unit tests for an app go here. │ ├── tests/ # All your integration and unit tests for an app go here.
│ ├── __init__.py
│ ├── admin.py │ ├── admin.py
│ ├── apps.py │ ├── apps.py
│ ├── __init__.py
│ ├── models.py │ ├── models.py
│ ├── services.py # Your business logic and data abstractions go here. │ ├── services.py # Your business logic and data abstractions go here.
│ ├── urls.py │ ├── urls.py
│ └── views.py │ └── views.py
├── common # An optional folder containing common &quot;stuff&quot; for the entire project ├── common/ # An optional folder containing common &quot;stuff&quot; for the entire project
├── config ├── config/
│ ├── settings.py
│ ├── asgi.py
│ ├── __init__.py │ ├── __init__.py
│ ├── asgi.py
│ ├── settings.py
│ ├── urls.py │ ├── urls.py
│ └── wsgi.py │ └── wsgi.py
├── deployments # Isolate Dockerfiles and docker-compose files here. ├── deployments/ # Isolate Dockerfiles and docker-compose files here.
├── docs ├── docs/
│ ├── CHANGELOG.md │ ├── CHANGELOG.md
│ ├── CONTRIBUTING.md │ ├── CONTRIBUTING.md
│ ├── deployment.md │ ├── deployment.md
│ ├── local-development.md │ ├── local-development.md
│ └── swagger.yaml │ └── swagger.yaml
├── requirements ├── requirements/
│ ├── common.txt # Same for all environments │ ├── common.txt # Same for all environments
│ ├── development.txt # Only for a development server │ ├── development.txt # Only for a development server
│ ├── local.txt # Only for a local server (example: docs, performance testing, etc.) │ ├── local.txt # Only for a local server (example: docs, performance testing, etc.)
│ └── production.txt # Production only │ └── production.txt # Production only
├── static # Your static files ├── static/ # Your static files
├── .env.example # An example of your .env configurations. Add necessary comments. ├── .env.example # An example of your .env configurations. Add necessary comments.
├── static # Your static files ├── .gitignore # https://github.com/github/gitignore/blob/main/Python.gitignore
├── .gitignore # https://github.com/github/gitignore/blob/main/Python.gitignore ├── entrypoint.sh # Any bootstrapping necessary for your application
├── entrypoint.sh # Any bootstrapping necessary for your application
├── manage.py ├── manage.py
├── pytest.ini ├── pytest.ini
└── README.md └── README.md
@ -687,7 +741,7 @@ into any other project and it’ll work independently.</p>
<li>A mother-folder containing all apps for our project. Congruent to any <li>A mother-folder containing all apps for our project. Congruent to any
JS-framework's <code>src</code> folder. If you really wanted to, you could even call it the JS-framework's <code>src</code> folder. If you really wanted to, you could even call it the
<code>src</code> folder. Again, it's up to you.</li> <code>src</code> folder. Again, it's up to you.</li>
<li>An app can be a django template project, or an rest framework API.</li> <li>An app can be a django template project, or a rest framework API.</li>
</ul> </ul>
<h3 id="services"><code>services</code></h3> <h3 id="services"><code>services</code></h3>
<ul> <ul>
@ -727,7 +781,8 @@ data is handled and managed within your application.</p>
<p>Sufficient unit tests and integration tests should wrap services and API <p>Sufficient unit tests and integration tests should wrap services and API
endpoints to ensure full compatibility.</p> endpoints to ensure full compatibility.</p>
<h4 id="whats-v2-of-an-api">What's <code>v2</code> of an API?</h4> <h4 id="whats-v2-of-an-api">What's <code>v2</code> of an API?</h4>
<p>Currently we're proposing that major changes to the following, constitutes a new API version: <p>Currently, we're proposing that major changes to the following constitutes a new
API version:
1. Representation of data, either for submission or retrieval 1. Representation of data, either for submission or retrieval
1. Major optimizations 1. Major optimizations
1. Major code reorganization and code refactor 1. Major code reorganization and code refactor
@ -749,6 +804,16 @@ different environments.</li>
who consumes your APIs. To learn how to create a custom exception handler, who consumes your APIs. To learn how to create a custom exception handler,
you can check out the Django Rest Framework documentation at: you can check out the Django Rest Framework documentation at:
https://www.django-rest-framework.org/api-guide/exceptions/#custom-exception-handling</p> https://www.django-rest-framework.org/api-guide/exceptions/#custom-exception-handling</p>
<h2 id="faq">FAQ</h2>
<blockquote>
<p>Why not just make a cookiecutter out of this?</p>
</blockquote>
<p>Honestly, GitHub templates are so much easier. It's a one-click solution and
you're good to go. If we want to turn this into a cookiecutter, we'd have to also
start deciding sensible defaults, for instance, sentry, DRF version, formatters,
linters, etc. And that's something better left to the developer. Although, I am
playing around with the idea of having a cookiecutter with those sensible
defaults, but let's hope we have time to work on it on the <code>cookiecutter</code> branch.</p>
<h2 id="references">References</h2> <h2 id="references">References</h2>
<ul> <ul>
<li><a href="https://www.feldroy.com/books/two-scoops-of-django-3-x">Two Scoops of Django by Daniel and Audrey Feldroy</a></li> <li><a href="https://www.feldroy.com/books/two-scoops-of-django-3-x">Two Scoops of Django by Daniel and Audrey Feldroy</a></li>
@ -758,6 +823,7 @@ https://www.django-rest-framework.org/api-guide/exceptions/#custom-exception-han
<li><a href="https://www.youtube.com/watch?v=yG3ZdxBb1oo">Radoslav Georgiev - Django Structure for Scale and Longevity</a></li> <li><a href="https://www.youtube.com/watch?v=yG3ZdxBb1oo">Radoslav Georgiev - Django Structure for Scale and Longevity</a></li>
<li><a href="https://apisyouwonthate.com/books/build-apis-you-wont-hate/">Build APIs You Won't Hate</a></li> <li><a href="https://apisyouwonthate.com/books/build-apis-you-wont-hate/">Build APIs You Won't Hate</a></li>
<li><a href="https://github.com/saqibur/tuxedo">Tuxedo Style Guides</a></li> <li><a href="https://github.com/saqibur/tuxedo">Tuxedo Style Guides</a></li>
<li><a href="https://www.django-antipatterns.com/">Django Anti Patterns</a></li>
</ul> </ul>
@ -780,7 +846,7 @@ https://www.django-rest-framework.org/api-guide/exceptions/#custom-exception-han
<div class="md-copyright"> <div class="md-copyright">
<div class="md-copyright__highlight"> <div class="md-copyright__highlight">
Copyright &copy; 2022 - 2023 Saqibur Rahman Copyright &copy; 2022 - 2024 Saqibur Rahman
</div> </div>

2
docs/search/search_index.json
View File

File diff suppressed because one or more lines are too long

2
docs/sitemap.xml
View File

@ -2,7 +2,7 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url> <url>
<loc>https://github.com/saqibur/django-project-structure/</loc> <loc>https://github.com/saqibur/django-project-structure/</loc>
<lastmod>2023-11-26</lastmod> <lastmod>2024-11-05</lastmod>
<changefreq>daily</changefreq> <changefreq>daily</changefreq>
</url> </url>
</urlset> </urlset>

BIN
docs/sitemap.xml.gz
View File

Binary file not shown.

102
mkdocs/index.md
View File

@ -1,6 +1,6 @@
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Python 3.12.3](https://img.shields.io/badge/python-3.12.3-blue.svg)](https://www.python.org/downloads/release/python-3123/)
[![Python 3.10.8](https://img.shields.io/badge/python-3.10.8-blue.svg)](https://www.python.org/downloads/release/python-3108//)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/)
![Django](https://img.shields.io/badge/django-%23092E20.svg?style=for-the-badge&logo=django&logoColor=white) ![Django](https://img.shields.io/badge/django-%23092E20.svg?style=for-the-badge&logo=django&logoColor=white)
![DjangoREST](https://img.shields.io/badge/DJANGO-REST-ff1709?style=for-the-badge&logo=django&logoColor=white&color=ff1709&labelColor=gray) ![DjangoREST](https://img.shields.io/badge/DJANGO-REST-ff1709?style=for-the-badge&logo=django&logoColor=white&color=ff1709&labelColor=gray)
@ -10,13 +10,21 @@
# Django Project Structure # Django Project Structure
This is a template/project structure for developing django-based applications - This is a template/project structure for developing django-based applications -
either strictly through the `django-rest-framework` or just `django`. using `django-rest-framework` along with `django`.
The project is meant to be easily clone-able, and used as the starter template The project is meant to be easily clone-able, and used as the starter template
for the next big thing you develop. Note, this is a folder structure only, not for the next big thing you develop. Note, this is a folder structure only, not
“best practices”. “best practices”.
## Some batteries included:
* [Django Storages](https://django-storages.readthedocs.io/en/stable/) - To integrate with different types of storages
* [Django Rest Framework](https://www.django-rest-framework.org/) - For API development
* [Django CORS Headers](https://github.com/adamchainz/django-cors-headers) - To allow requests from other origins
* [Sentry](https://docs.sentry.io/platforms/python/) - For crashes
* [Gunicorn](https://gunicorn.org/) - As a web server
## Getting Started ## Getting Started
1. Since this is a template repository, simply hit "Use this template" on GitHub 1. Since this is a template repository, simply hit "Use this template" on GitHub
and follow the instructions. Otherwise, you can just clone the repo, remove/add and follow the instructions. Otherwise, you can just clone the repo, remove/add
@ -24,6 +32,20 @@ anything you see fit.
1. Run the project using `python manage.py runserver` and you should see the 1. Run the project using `python manage.py runserver` and you should see the
default success page provided by Django at default success page provided by Django at
[http://127.0.0.1:8000/](http://127.0.0.1:8000/). [http://127.0.0.1:8000/](http://127.0.0.1:8000/).
1. [Optional] If you want to configure database, in the `DATABASE` section of
`settings.py` we have added `postgresql` as the default `DATABASE` (As most of
the application are using it). You can roll back to the `sqlite` by adding the
following code snippet, removing the current one.
```bash
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
}
}
```
### Creating an App ### Creating an App
1. Create a folder with the app name in `apps`. For example: `poll` 1. Create a folder with the app name in `apps`. For example: `poll`
@ -34,60 +56,59 @@ project
## Project Tree ## Project Tree
``` bash ``` bash
. .
├── apps ├── apps/
│ └── example # A django rest app │ └── example/ # A django rest app
│ ├── api │ ├── api/
│ │ ├── v1 # Only the "presentation" layer exists here. │ │ ├── v1/ # Only the "presentation" layer exists here.
│ │ │ ├── __init__.py │ │ │ ├── __init__.py
│ │ │ ├── serializers.py │ │ │ ├── serializers.py
│ │ │ ├── urls.py │ │ │ ├── urls.py
│ │ │ └── views.py │ │ │ └── views.py
│ │ ├── v2 # Only the "presentation" layer exists here. │ │ ├── v2 # Only the "presentation" layer exists here.
│ │ │ ├── __init__.py │ │ │ ├── __init__.py
│ │ │ ├── serializers.py │ │ │ ├── serializers.py
│ │ │ ├── urls.py │ │ │ ├── urls.py
│ │ │ └── views.py │ │ │ └── views.py
│ │ └── __init__.py │ │ └── __init__.py
│ ├── fixtures # Constant "seeders" to populate your database │ ├── fixtures/ # Constant "seeders" to populate your database
│ ├── management │ ├── management/
│ │ ├── commands # Try and write some database seeders here │ │ ├── commands/ # Try and write some database seeders here
│ │ │ └── command.py │ │ │ └── command.py
│ │ └── __init__.py │ │ └── __init__.py
│ ├── migrations │ ├── migrations/
│ │ └── __init__.py │ │ └── __init__.py
│ ├── templates # App-specific templates go here │ ├── templates/ # App-specific templates go here
│ ├── tests # All your integration and unit tests for an app go here. │ ├── tests/ # All your integration and unit tests for an app go here.
│ ├── __init__.py
│ ├── admin.py │ ├── admin.py
│ ├── apps.py │ ├── apps.py
│ ├── __init__.py
│ ├── models.py │ ├── models.py
│ ├── services.py # Your business logic and data abstractions go here. │ ├── services.py # Your business logic and data abstractions go here.
│ ├── urls.py │ ├── urls.py
│ └── views.py │ └── views.py
├── common # An optional folder containing common "stuff" for the entire project ├── common/ # An optional folder containing common "stuff" for the entire project
├── config ├── config/
│ ├── settings.py
│ ├── asgi.py
│ ├── __init__.py │ ├── __init__.py
│ ├── asgi.py
│ ├── settings.py
│ ├── urls.py │ ├── urls.py
│ └── wsgi.py │ └── wsgi.py
├── deployments # Isolate Dockerfiles and docker-compose files here. ├── deployments/ # Isolate Dockerfiles and docker-compose files here.
├── docs ├── docs/
│ ├── CHANGELOG.md │ ├── CHANGELOG.md
│ ├── CONTRIBUTING.md │ ├── CONTRIBUTING.md
│ ├── deployment.md │ ├── deployment.md
│ ├── local-development.md │ ├── local-development.md
│ └── swagger.yaml │ └── swagger.yaml
├── requirements ├── requirements/
│ ├── common.txt # Same for all environments │ ├── common.txt # Same for all environments
│ ├── development.txt # Only for a development server │ ├── development.txt # Only for a development server
│ ├── local.txt # Only for a local server (example: docs, performance testing, etc.) │ ├── local.txt # Only for a local server (example: docs, performance testing, etc.)
│ └── production.txt # Production only │ └── production.txt # Production only
├── static # Your static files ├── static/ # Your static files
├── .env.example # An example of your .env configurations. Add necessary comments. ├── .env.example # An example of your .env configurations. Add necessary comments.
├── static # Your static files ├── .gitignore # https://github.com/github/gitignore/blob/main/Python.gitignore
├── .gitignore # https://github.com/github/gitignore/blob/main/Python.gitignore ├── entrypoint.sh # Any bootstrapping necessary for your application
├── entrypoint.sh # Any bootstrapping necessary for your application
├── manage.py ├── manage.py
├── pytest.ini ├── pytest.ini
└── README.md └── README.md
@ -103,7 +124,7 @@ into any other project and it’ll work independently.
* A mother-folder containing all apps for our project. Congruent to any * A mother-folder containing all apps for our project. Congruent to any
JS-framework's `src` folder. If you really wanted to, you could even call it the JS-framework's `src` folder. If you really wanted to, you could even call it the
`src` folder. Again, it's up to you. `src` folder. Again, it's up to you.
* An app can be a django template project, or an rest framework API. * An app can be a django template project, or a rest framework API.
### `services` ### `services`
* We’ll be writing business logic in services instead of anywhere else. * We’ll be writing business logic in services instead of anywhere else.
@ -148,7 +169,8 @@ endpoints to ensure full compatibility.
#### What's `v2` of an API? #### What's `v2` of an API?
Currently we're proposing that major changes to the following, constitutes a new API version: Currently, we're proposing that major changes to the following constitutes a new
API version:
1. Representation of data, either for submission or retrieval 1. Representation of data, either for submission or retrieval
1. Major optimizations 1. Major optimizations
1. Major code reorganization and code refactor 1. Major code reorganization and code refactor
@ -173,6 +195,17 @@ you can check out the Django Rest Framework documentation at:
https://www.django-rest-framework.org/api-guide/exceptions/#custom-exception-handling https://www.django-rest-framework.org/api-guide/exceptions/#custom-exception-handling
## FAQ
> Why not just make a cookiecutter out of this?
Honestly, GitHub templates are so much easier. It's a one-click solution and
you're good to go. If we want to turn this into a cookiecutter, we'd have to also
start deciding sensible defaults, for instance, sentry, DRF version, formatters,
linters, etc. And that's something better left to the developer. Although, I am
playing around with the idea of having a cookiecutter with those sensible
defaults, but let's hope we have time to work on it on the `cookiecutter` branch.
## References ## References
- [Two Scoops of Django by Daniel and Audrey Feldroy](https://www.feldroy.com/books/two-scoops-of-django-3-x) - [Two Scoops of Django by Daniel and Audrey Feldroy](https://www.feldroy.com/books/two-scoops-of-django-3-x)
- [Django Best Practices](https://django-best-practices.readthedocs.io/en/latest/index.html) - [Django Best Practices](https://django-best-practices.readthedocs.io/en/latest/index.html)
@ -181,3 +214,4 @@ https://www.django-rest-framework.org/api-guide/exceptions/#custom-exception-han
- [Radoslav Georgiev - Django Structure for Scale and Longevity](https://www.youtube.com/watch?v=yG3ZdxBb1oo) - [Radoslav Georgiev - Django Structure for Scale and Longevity](https://www.youtube.com/watch?v=yG3ZdxBb1oo)
- [Build APIs You Won't Hate](https://apisyouwonthate.com/books/build-apis-you-wont-hate/) - [Build APIs You Won't Hate](https://apisyouwonthate.com/books/build-apis-you-wont-hate/)
- [Tuxedo Style Guides](https://github.com/saqibur/tuxedo) - [Tuxedo Style Guides](https://github.com/saqibur/tuxedo)
- [Django Anti Patterns](https://www.django-antipatterns.com/)