From aa2f4ae9b358169176f61eea173949daeb1faf41 Mon Sep 17 00:00:00 2001 From: styx0x6 Date: Fri, 25 Oct 2024 19:33:15 +0000 Subject: [PATCH] WhiteNoise and other libraries docs --- docs/Credits.md | 11 ++++-- docs/General.md | 87 ++++++++++++++++++++++++++++++++--------------- docs/index.rst.j2 | 2 +- 3 files changed, 69 insertions(+), 31 deletions(-) diff --git a/docs/Credits.md b/docs/Credits.md index 5616b35..c6ebc31 100644 --- a/docs/Credits.md +++ b/docs/Credits.md @@ -25,9 +25,13 @@ [![Licence: MIT](https://img.shields.io/badge/Licence-MIT-chartreuse)](https://github.com/evansd/whitenoise?tab=MIT-1-ov-file#readme) [github.com/evansd/whitenoise](https://github.com/evansd/whitenoise) -* **Bootstrap** - TODO +* **AdminLTE** - HTML admin templates & components based on Bootstrap. + + Copyright 2014-2024 Colorlib + [![Licence: MIT](https://img.shields.io/badge/Licence-MIT-chartreuse)](https://github.com/ColorlibHQ/AdminLTE/blob/master/LICENSE) + [AdminLTE.io](https://adminlte.io) -* **AdminLTE** - TODO +* **Bootstrap** - TODO * **Sphinx** - TODO @@ -48,3 +52,6 @@ [![Licence: CC0](https://img.shields.io/badge/License-CC0-lightgrey)](https://github.com/badges/shields?tab=CC0-1.0-1-ov-file#readme) [shields.io](https://shields.io) [github.com/badges/shields](https://github.com/badges/shields) + +* **Simple Icons** - TODO + diff --git a/docs/General.md b/docs/General.md index c211dff..fb83826 100644 --- a/docs/General.md +++ b/docs/General.md @@ -1,6 +1,6 @@ # General -This **Developer Documentation** can be refered as **"CodeDoc"**. +This **Developer Documentation** may be refered as **"CodeDoc"**. ## Development Environment @@ -8,16 +8,18 @@ This **Developer Documentation** can be refered as **"CodeDoc"**. Create a personal **GitHub Codespaces** from scratch with ```colvert-project/colvert``` and ```origin/main``` remote repository. -Some Visual Studio Code extensions can be settled in addition: +Some Visual Studio Code extensions can be settled in addition of default ones: -* Python -* Python Debugger -* Pylance -* GitHub Actions +* Python (_Microsoft_) +* Python Debugger (_Microsoft_) +* Pylance (_Microsoft_) +* GitHub Actions (_GitHub_) +* markdownlint (_David Anson_) +* Docker (_Microsoft_) As reminder, in **GitHub Codespaces** states concerning opened tabs and settings (like color theme, etc.) are not saved until you set _Backup and Sync Settings_. -### Documentation Build +## Documentation Build It uses **Sphinx** with a third-party GitHub workflow in `.github/workflows/build-docs.yml` to trigger build on `git push` action. It uses the third-party action [`sphinx-notes/pages@v3`](https://github.com/sphinx-notes/pages). @@ -36,17 +38,47 @@ Help links: # Architecture -[![Python 3.12+](https://img.shields.io/badge/Python-3.12+-blue?logo=python&logoColor=white&labelColor=3776ab&color=ffd43b)](https://www.python.org) -[![Django 5.1](https://img.shields.io/badge/Django-5.1-white?logo=django&logoColor=white&labelColor=092e20)](https://www.djangoproject.com) -([![Bootstrap 5](https://img.shields.io/badge/Bootstrap-5.3-white?logo=bootstrap&logoColor=white&labelColor=7952b3)](getbootstrap.com)) +**Colvert** is a web application written in **_Python_ 3**, built on **_Django_ 5** web framework with **_AdminLTE 4_** templates library for view and control parts, itself based on **_Bootstrap_ 5**. + +## Packages & Libraries + +|Library|Type|Version|Purpose| +|----------|------|------|-| +|_Python_ |Engine|3.12.1 |Language in which Colvert is written with| +|**Django** |Python|5.1.1 |Web Application Framework (Basic application features, Templating, ORM)| +|**WhiteNoise**|Python|6.7.0 |Server properly static files in production **AND** in debug mode| +|AdminLTE |CSS+JS|4.0.0-beta2|Front-end library used with HTML templates| +|Bootstrap |CSS+JS|5().3? || + +* Type means type of library. + +* In `requirements.txt`, versions are fixed. +* In Python package, versions must be assume as 'at least', to let potential already deployed packages as is. + + [![AdminLTE 4.0](https://img.shields.io/npm/v/admin-lte/latest.svg)](https://www.npmjs.com/package/admin-lte) + _TODO_ Fix version, not latest + + ([![Bootstrap 5.3](https://img.shields.io/badge/Bootstrap-5.3-white?logo=bootstrap&logoColor=white&labelColor=7952b3)](getbootstrap.com)) + +### Dependencies Matrix + +* _TODO_ Check with GitHub Dependabot + +### Official Documentation + +* Python + + + +* WhiteNoise AdminLTE -**Colvert** is a web application written in **_Python_ 3**, built on **_Django_ 5** web framework with **_AdminLTE 4_** as **_Bootstrap_ 5** template for view and control parts. +* Bootstrap ## Project Setup -### Packages Installation +### Libraries Installation ```shell /workspaces/colvert (main) $ python --version @@ -56,18 +88,13 @@ pip 24.2 from /usr/local/python/3.12.1/lib/python3.12/site-packages/pip (python ``` ```shell - /workspaces/colvert (main) $ python -m pip install Django - ... - Successfully installed Django-5.1.1 asgiref-3.8.1 sqlparse-0.5.1 - /workspaces/colvert (main) $ django-admin --version - 5.1.1 +/workspaces/colvert (main) $ python -m pip -r requirements.txt ``` -```shell - /workspaces/colvert (main) $ python -m pip install WhiteNoise - ... - Successfully installed whitenoise-6.7.0 -``` + + + +* Applying Quickstart (only for MIDDLEWARE), 1., 2. & 5. ### Django Project Initialization @@ -89,8 +116,7 @@ Hint: - + Bootstrap and AdminLTE installed in minimal version: @@ -120,10 +146,15 @@ For future library update, run again commands above by replacing the Bootstrap / Update `requirements.txt` ```shell -python manage.py migrate -python manage.py runserver +python manage.py migrate # To update model if changed +python manage.py collectstatic # To publish all static files in STATIC_ROOT if new ones need to +python manage.py runserver # Start development server ``` -TODO - Collect staticfiles - TODO - Merge migrations + +#### References + + + + diff --git a/docs/index.rst.j2 b/docs/index.rst.j2 index c1d9366..f267384 100644 --- a/docs/index.rst.j2 +++ b/docs/index.rst.j2 @@ -29,7 +29,7 @@ Go to the main repository `https://github.com/colvert-project/colvert`_ for an o .. toctree:: :maxdepth: 3 - :caption: Usage Guides + :caption: Usage Guide Getting-Started.md