From b78d9496867a13ed096b4b1f561a47a25001a901 Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Fri, 25 Feb 2022 01:10:45 +0100 Subject: Add a readme to the Django project directory --- pydis_site/README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 pydis_site/README.md (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md new file mode 100644 index 00000000..456f7e9e --- /dev/null +++ b/pydis_site/README.md @@ -0,0 +1,52 @@ +# `pydis_site` project directory + +This directory hosts the root of our **Django project**[^1], and is responsible +for all logic powering our website. Let's go over the directories in detail: + +- [`apps`](./apps) contains our **Django apps**. If you want to add your own API + endpoint or new functionality to our homepage, that's the place to go. + + +- [`static`](./static) contains our **static files**, such as CSS, JavaScript, + images, and anything else that isn't either content or Python code. Static + files relevant for a specific application are put into subdirectories named + after the application. + +- [`templates`](./templates) contains our **Django templates**. Like with static + files, templates specific to a single application are stored in a subdirectory + named after that application. We also have two special templates here: + + - `404.html`, which is our error page shown when a site was not found. + + - `500.html`, which is our error page shown in the astronomically rare case + that we encounter an internal server error. + + +We also have a few files in here that are relevant or useful in large parts of +the website: + +- [`context_processors.py`](./context_processors.py), which contains custom + *context processors* that add variables to the Django template context. To + read more, see the [`RequestContext` documentation from + Django](https://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext) + +- [`settings.py`](./settings.py), our Django settings file. This mostly just + parses configuration out of your environment variables, so you shouldn't need + to edit it directly unless you want to add new settings. + +- [`urls.py`](./urls.py), which configures our Django URL routing by installing + our apps into the routing tree. + +- [`wsgi.py`](./wsgi.py), which serves as an adapter for + [`gunicorn`](https://github.com/benoitc/gunicorn), + [`uwsgi`](https://github.com/unbit/uwsgi) or other application servers to run + our application in production. Unless you want to test an interaction between + our application and those servers, you probably won't need to touch this. + +Note that for both `static` and `templates`, we are not using the default Django +directory structure which puts these directories in a directory per app (in our +case, this would for example be ``pydis_site/apps/content/static/``). + + +[^1]: See [Django Glossary: project](https://docs.djangoproject.com/en/dev/glossary/#term-project) -- cgit v1.2.3 From 2e02f8672212b70f6be5349288b0d932e6d35b52 Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Sat, 26 Feb 2022 13:29:54 +0100 Subject: Move static & template folder description up --- pydis_site/README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index 456f7e9e..77cfbeab 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -23,6 +23,11 @@ for all logic powering our website. Let's go over the directories in detail: that we encounter an internal server error. + +Note that for both `static` and `templates`, we are not using the default Django +directory structure which puts these directories in a directory per app (in our +case, this would for example be ``pydis_site/apps/content/static/``). + We also have a few files in here that are relevant or useful in large parts of the website: @@ -44,9 +49,5 @@ the website: our application in production. Unless you want to test an interaction between our application and those servers, you probably won't need to touch this. -Note that for both `static` and `templates`, we are not using the default Django -directory structure which puts these directories in a directory per app (in our -case, this would for example be ``pydis_site/apps/content/static/``). - [^1]: See [Django Glossary: project](https://docs.djangoproject.com/en/dev/glossary/#term-project) -- cgit v1.2.3 From d5c3d0b300412f2914211e18d85870bdee426a73 Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Sat, 26 Feb 2022 15:03:59 +0100 Subject: Comment in individual application doc reference --- pydis_site/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index 77cfbeab..6b496c05 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -3,10 +3,10 @@ This directory hosts the root of our **Django project**[^1], and is responsible for all logic powering our website. Let's go over the directories in detail: -- [`apps`](./apps) contains our **Django apps**. If you want to add your own API - endpoint or new functionality to our homepage, that's the place to go. - +- [`apps`](./apps) contains our **Django apps**. If you want to add your own + API endpoint or new functionality to our homepage, that's the place to go. + Each individual application also has its own README.md that you can click + through. - [`static`](./static) contains our **static files**, such as CSS, JavaScript, images, and anything else that isn't either content or Python code. Static -- cgit v1.2.3 From fee126891924a6f6af492613c4cb7635d9cd3289 Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Sat, 26 Feb 2022 15:07:15 +0100 Subject: Document Django applications in more depth --- pydis_site/README.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index 6b496c05..f70bbf51 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -3,10 +3,15 @@ This directory hosts the root of our **Django project**[^1], and is responsible for all logic powering our website. Let's go over the directories in detail: -- [`apps`](./apps) contains our **Django apps**. If you want to add your own - API endpoint or new functionality to our homepage, that's the place to go. - Each individual application also has its own README.md that you can click - through. +- [`apps`](./apps) contains our **Django apps**, which are the building blocks + that make up our Django project. A Django project must always consist of one + or more apps, and these apps can be made completely modular and reusable + across any Django project. In our project, each app controls a distinct part + of our website, such as the API or our resources system. For more + information on reusable apps, see the official Django tutorial, [which has a + section on reusable + apps](https://docs.djangoproject.com/en/dev/intro/reusable-apps/). To learn + more about our specific apps, see the README inside the app folder itself. - [`static`](./static) contains our **static files**, such as CSS, JavaScript, images, and anything else that isn't either content or Python code. Static -- cgit v1.2.3 From 851746368a4906dd6db456228ff0ce8b78419943 Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Sat, 26 Feb 2022 15:09:54 +0100 Subject: Link to Django template documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Leon Sandøy --- pydis_site/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index f70bbf51..b2470500 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -18,7 +18,7 @@ for all logic powering our website. Let's go over the directories in detail: files relevant for a specific application are put into subdirectories named after the application. -- [`templates`](./templates) contains our **Django templates**. Like with static +- [`templates`](./templates) contains our **[Django templates](https://docs.djangoproject.com/en/dev/topics/templates/)**. Like with static files, templates specific to a single application are stored in a subdirectory named after that application. We also have two special templates here: -- cgit v1.2.3 From bd3a12eb14b85ee827505652263263baa44c5132 Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Sat, 26 Feb 2022 15:10:08 +0100 Subject: Remove newlines added by an 🥥 INSANE PERSON 🥥 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Leon Sandøy --- pydis_site/README.md | 1 - 1 file changed, 1 deletion(-) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index b2470500..cc0ec2a8 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -28,7 +28,6 @@ for all logic powering our website. Let's go over the directories in detail: that we encounter an internal server error. - Note that for both `static` and `templates`, we are not using the default Django directory structure which puts these directories in a directory per app (in our case, this would for example be ``pydis_site/apps/content/static/``). -- cgit v1.2.3 From 143e0ad3bbcb3d2695dfb398db3846b87a9581d8 Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Sat, 26 Feb 2022 15:12:27 +0100 Subject: Elaborate on purpose of the urls module MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Leon Sandøy --- pydis_site/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index cc0ec2a8..b0b6d122 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -44,8 +44,7 @@ the website: parses configuration out of your environment variables, so you shouldn't need to edit it directly unless you want to add new settings. -- [`urls.py`](./urls.py), which configures our Django URL routing by installing - our apps into the routing tree. +- [`urls.py`](./urls.py), the URL configuration for the project itself. Here we can forward certain URL paths to our different apps, which have their own `urls.py` files to configure where their subpaths will lead. These files determine _which URLs will lead to which Django views_. - [`wsgi.py`](./wsgi.py), which serves as an adapter for [`gunicorn`](https://github.com/benoitc/gunicorn), -- cgit v1.2.3 From 69c88813d95e04abe17f6fadab221cce5d5bb619 Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Sat, 26 Feb 2022 15:18:55 +0100 Subject: Elaborate on settings.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Leon Sandøy --- pydis_site/README.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index b0b6d122..8aa7b1f6 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -18,9 +18,11 @@ for all logic powering our website. Let's go over the directories in detail: files relevant for a specific application are put into subdirectories named after the application. -- [`templates`](./templates) contains our **[Django templates](https://docs.djangoproject.com/en/dev/topics/templates/)**. Like with static - files, templates specific to a single application are stored in a subdirectory - named after that application. We also have two special templates here: +- [`templates`](./templates) contains our **[Django + templates](https://docs.djangoproject.com/en/dev/topics/templates/)**. Like + with static files, templates specific to a single application are stored in a + subdirectory named after that application. We also have two special templates + here: - `404.html`, which is our error page shown when a site was not found. @@ -40,11 +42,16 @@ the website: read more, see the [`RequestContext` documentation from Django](https://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext) -- [`settings.py`](./settings.py), our Django settings file. This mostly just - parses configuration out of your environment variables, so you shouldn't need - to edit it directly unless you want to add new settings. +- [`settings.py`](./settings.py), our Django settings file. This controls all + manner of crucial things, for instance, we use it to configure logging, our + connection to the database, which applications are run by the project, which + middleware we are using, and variables for `django-simple-bulma` (which + determines frontend colours & extensions for our pages). -- [`urls.py`](./urls.py), the URL configuration for the project itself. Here we can forward certain URL paths to our different apps, which have their own `urls.py` files to configure where their subpaths will lead. These files determine _which URLs will lead to which Django views_. +- [`urls.py`](./urls.py), the URL configuration for the project itself. Here we + can forward certain URL paths to our different apps, which have their own + `urls.py` files to configure where their subpaths will lead. These files + determine _which URLs will lead to which Django views_. - [`wsgi.py`](./wsgi.py), which serves as an adapter for [`gunicorn`](https://github.com/benoitc/gunicorn), -- cgit v1.2.3 From 8eca5c8ddeed9ef7b827da9f6e87df034c073d6d Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Sat, 26 Feb 2022 16:06:57 +0100 Subject: Add newlines for the apps section --- pydis_site/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index 8aa7b1f6..a789230d 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -7,9 +7,10 @@ for all logic powering our website. Let's go over the directories in detail: that make up our Django project. A Django project must always consist of one or more apps, and these apps can be made completely modular and reusable across any Django project. In our project, each app controls a distinct part - of our website, such as the API or our resources system. For more - information on reusable apps, see the official Django tutorial, [which has a - section on reusable + of our website, such as the API or our resources system. + + For more information on reusable apps, see the official Django tutorial, + [which has a section on reusable apps](https://docs.djangoproject.com/en/dev/intro/reusable-apps/). To learn more about our specific apps, see the README inside the app folder itself. -- cgit v1.2.3 From 004751addf89984fa033a57e5af10af53eebfec2 Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Mon, 28 Feb 2022 11:14:44 +0100 Subject: Add serial comma Co-authored-by: Mark <1515135+MarkKoz@users.noreply.github.com> --- pydis_site/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index a789230d..7c76df55 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -56,7 +56,7 @@ the website: - [`wsgi.py`](./wsgi.py), which serves as an adapter for [`gunicorn`](https://github.com/benoitc/gunicorn), - [`uwsgi`](https://github.com/unbit/uwsgi) or other application servers to run + [`uwsgi`](https://github.com/unbit/uwsgi), or other application servers to run our application in production. Unless you want to test an interaction between our application and those servers, you probably won't need to touch this. -- cgit v1.2.3 From cdb7af596f7b9d0645bc145be240444527cadf34 Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Mon, 28 Feb 2022 11:15:04 +0100 Subject: Add reference to the `resources` app MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Leon Sandøy --- pydis_site/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index 7c76df55..bf039ad7 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -17,7 +17,7 @@ for all logic powering our website. Let's go over the directories in detail: - [`static`](./static) contains our **static files**, such as CSS, JavaScript, images, and anything else that isn't either content or Python code. Static files relevant for a specific application are put into subdirectories named - after the application. + after the application. For example, static files used by the `resources` app go in `static/resources`. - [`templates`](./templates) contains our **[Django templates](https://docs.djangoproject.com/en/dev/topics/templates/)**. Like -- cgit v1.2.3 From 9d5b0baa721dbdb1f4cf2529df1f71339defaf0c Mon Sep 17 00:00:00 2001 From: Johannes Christ Date: Mon, 28 Feb 2022 18:11:45 +0100 Subject: Add link to contributing guide --- pydis_site/README.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'pydis_site/README.md') diff --git a/pydis_site/README.md b/pydis_site/README.md index bf039ad7..db402743 100644 --- a/pydis_site/README.md +++ b/pydis_site/README.md @@ -61,4 +61,8 @@ the website: our application and those servers, you probably won't need to touch this. +For more information about contributing to our projects, please see our +[Contributing +page](https://www.pythondiscord.com/pages/guides/pydis-guides/contributing/). + [^1]: See [Django Glossary: project](https://docs.djangoproject.com/en/dev/glossary/#term-project) -- cgit v1.2.3