more docs

Archmonger · Aug 27, 2022 · eb6283e · eb6283e
1 parent 4fdc1dd
commit eb6283e
Show file tree

Hide file tree

Showing 41 changed files with 105 additions and 94 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,11 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
-<!--attr-start-->
+<!-- attr -->
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-<!--attr-end-->
+<!-- attr-end -->
 
 <!--
 Using the following categories, list your changes in this order:
@@ -18,7 +18,7 @@ Using the following categories, list your changes in this order:
     - "Security" in case of vulnerabilities.
  -->
 
-<!--changelog-start-->
+<!-- changelog -->
 
 ## [Unreleased]
 
@@ -32,3 +32,5 @@ Using the following categories, list your changes in this order:
 
 [unreleased]: https://github.com/Archmonger/Conreq/compare/0.100.0...HEAD
 [0.100.0]: https://github.com/Archmonger/Conreq/releases/tag/0.100.0
+
+<!-- changelog-end -->
diff --git a/conreq/_core/initialization/views.py b/conreq/_core/initialization/views.py
@@ -7,6 +7,7 @@
 INITIALIZED = False
 
 
+# TODO: Have an "IMPORT BACKUP" button that will import a backup file, if one exists.
 def initialize(request):
     # pylint: disable=global-statement
     # Check cached value if we've already initialized

diff --git a/conreq/_core/server_settings/forms.py b/conreq/_core/server_settings/forms.py
@@ -171,7 +171,7 @@ class WebserverSettingsForm(EnvFormMixin, ModelForm):
         env_name="WEBSERVER_WORKERS",
         initial=settings.WEBSERVER_WORKERS,
         required=True,
-        help_text="Number of separate worker processes for the webserver to use. <b>Each worker uses additional memory.</b>",
+        help_text="Number of separate worker processes for the webserver to use. <b>Each worker uses approximately 80MB additional memory.</b>",
     )
     webserver_debug = EnvBooleanField(
         env_name="WEBSERVER_DEBUG",

diff --git a/conreq/app/register/__init__.py b/conreq/app/register/__init__.py
@@ -1,21 +1,21 @@
 from conreq.app.register import (
-    component,
+    components,
     homepage,
     http,
     startup,
     tabs,
-    template,
-    view,
+    templates,
+    views,
     websockets,
 )
 
 __all__ = [
     "websockets",
-    "component",
+    "components",
     "homepage",
     "startup",
     "tabs",
-    "template",
-    "view",
+    "templates",
+    "views",
     "http",
 ]
diff --git a/conreq/app/render/__init__.py → conreq/app/register/backup.py b/conreq/app/render/__init__.py → conreq/app/register/backup.py
diff --git a/conreq/app/register/component.py → conreq/app/register/components.py b/conreq/app/register/component.py → conreq/app/register/components.py
diff --git a/conreq/app/register/http.py b/conreq/app/register/http.py
@@ -40,6 +40,11 @@ def decorator(view):
     return decorator
 
 
+def csrf_origin(url: str):
+    # TODO:  Implement this later
+    return None
+
+
 def _register_view(view, url_pattern, url_patterns, name, use_regex):
     registered_view = view.as_view() if hasattr(view, "as_view") else view
     dotted_path = f"{view.__module__}.{view.__name__}".replace("<", "").replace(">", "")

diff --git a/conreq/app/register/notification.py → conreq/app/register/notifications.py b/conreq/app/register/notification.py → conreq/app/register/notifications.py
diff --git a/conreq/app/register/template.py → conreq/app/register/templates.py b/conreq/app/register/template.py → conreq/app/register/templates.py
diff --git a/conreq/app/register/view.py → conreq/app/register/views.py b/conreq/app/register/view.py → conreq/app/register/views.py
diff --git a/conreq/app/register/websockets.py b/conreq/app/register/websockets.py
@@ -5,29 +5,18 @@
 from conreq.utils.environment import get_base_url
 
 BASE_URL = get_base_url(prepend_slash=False, empty_if_unset=True)
+# TODO: Implement ASGI middleware
 
 
-def websocket(path: str, use_regex: bool = False) -> AsyncConsumer:
+def websocket(path: str, use_regex: bool = False):
     """Decorates a websocket consumer class."""
 
-    def decorator(class_: AsyncConsumer):
-
+    def decorator(consumer: AsyncConsumer):
         websockets = config.asgi.websockets
         if not use_regex:
-            websockets.append(urls.path(BASE_URL + path, class_.as_asgi()))
+            websockets.append(urls.path(BASE_URL + path, consumer.as_asgi()))  # type: ignore
         else:
-            websockets.append(urls.re_path(BASE_URL + path, class_.as_asgi()))
-
-        return class_
+            websockets.append(urls.re_path(BASE_URL + path, consumer.as_asgi()))  # type: ignore
+        return consumer
 
     return decorator
-
-
-def middleware(
-    dotted_path: str,
-    positioning_elements: list[str] = None,
-    positioning: str = "before",
-    reverse: bool = False,
-) -> None:
-    """Shortcut to add ASGI middleware to Django."""
-    # TODO: Implement ASGI middleware
diff --git a/conreq/app/render/home.py b/conreq/app/render/home.py
diff --git a/conreq/app/render/modal.py b/conreq/app/render/modal.py
diff --git a/conreq/app/render/toast_message.py b/conreq/app/render/toast_message.py
diff --git a/docs/src/changelog/index.md b/docs/src/changelog/index.md
@@ -0,0 +1,5 @@
+???+ note "Attribution"
+
+    {% include-markdown "../../../CHANGELOG.md" start="<!-- attr -->" end="<!-- attr-end -->" trailing-newlines=false %}
+
+{% include-markdown "../../../CHANGELOG.md" start="<!-- changelog -->" end="<!-- changelog-end -->" %}
diff --git a/docs/src/developers/interface/python.md → docs/src/developers/contribute/source.md b/docs/src/developers/interface/python.md → docs/src/developers/contribute/source.md
diff --git a/docs/src/placeholder.md → ...developers/interface/python/components.md b/docs/src/placeholder.md → ...developers/interface/python/components.md
diff --git a/docs/src/developers/interface/python/fields.md b/docs/src/developers/interface/python/fields.md
diff --git a/docs/src/developers/interface/python/forms.md b/docs/src/developers/interface/python/forms.md
diff --git a/docs/src/developers/interface/python/models.md b/docs/src/developers/interface/python/models.md
diff --git a/docs/src/developers/interface/python/register/backup.md b/docs/src/developers/interface/python/register/backup.md
diff --git a/docs/src/developers/interface/python/register/components.md b/docs/src/developers/interface/python/register/components.md
diff --git a/docs/src/developers/interface/python/register/homepage.md b/docs/src/developers/interface/python/register/homepage.md
diff --git a/docs/src/developers/interface/python/register/http.md b/docs/src/developers/interface/python/register/http.md
diff --git a/docs/src/developers/interface/python/register/notifications.md b/docs/src/developers/interface/python/register/notifications.md
diff --git a/docs/src/developers/interface/python/register/startup.md b/docs/src/developers/interface/python/register/startup.md
diff --git a/docs/src/developers/interface/python/register/tabs.md b/docs/src/developers/interface/python/register/tabs.md
diff --git a/docs/src/developers/interface/python/register/templates.md b/docs/src/developers/interface/python/register/templates.md
diff --git a/docs/src/developers/interface/python/register/views.md b/docs/src/developers/interface/python/register/views.md
diff --git a/docs/src/developers/interface/python/register/websockets.md b/docs/src/developers/interface/python/register/websockets.md
diff --git a/docs/src/developers/interface/python/services/email.md b/docs/src/developers/interface/python/services/email.md
diff --git a/docs/src/developers/interface/python/validators.md b/docs/src/developers/interface/python/validators.md
diff --git a/docs/src/developers/interface/python/views.md b/docs/src/developers/interface/python/views.md
diff --git a/docs/src/developers/interface/python/widgets.md b/docs/src/developers/interface/python/widgets.md
diff --git a/docs/src/install/freebsd.md b/docs/src/install/freebsd.md
diff --git a/docs/src/install/macos.md b/docs/src/install/macos.md
diff --git a/docs/src/stylesheets/extra.css b/docs/src/stylesheets/extra.css
@@ -1,5 +1,5 @@
 .md-footer__inner {
-	display: none;
+	display: none !important;
 }
 
 .md-typeset :is(.admonition, details) {

diff --git a/docs/src/users/getting_started.md b/docs/src/users/getting_started.md
@@ -0,0 +1,7 @@
+Start Conreq
+
+Navigate to http://xxxx:7575
+
+Follow the setup procedures
+
+Feel free to expose Conreq to the internet
diff --git a/docs/src/users/optimizations.md b/docs/src/users/optimizations.md
@@ -0,0 +1,20 @@
+Include security and performance changes that can be made
+
+## Security
+
+-   Configure Conreq to use SSL
+-   Use system variables for secret keys
+-   Limit allowed hosts to only include URLs Conreq will be served at (local URLs can also be safe)
+-   Limit CSRF trusted origins
+-   Ensure Debug Mode is turned off whenever exposing Conreq to the internet
+-   Reduce max session age
+-   Enable Rotate Secret Key
+-   Configure email settings to receive security alerts
+
+## Performance
+
+-   Use Nginx with `X-Accel` (View reverse proxy docs)
+-   Increase worker count
+-   Reduce logging
+-   Use a production database, such as MySQL
+-   Use a high performance cache, such as Redis
diff --git a/docs/src/users/reverse_proxy.md b/docs/src/users/reverse_proxy.md
@@ -0,0 +1,7 @@
+???+ Summary
+
+    You can reverse proxy Conreq, but make sure to allow websockets and set your proxy headers.
+
+There are situations that you may want to reverse proxy Conreq, such as with distributed computing or for traffic optimization.
+
+1.  Set Allowed Forwarding IPs
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -2,33 +2,58 @@
 nav:
     - Home: index.md
     - Install:
-          - Operating System:
-                - Unraid: install/unraid.md
-                - Windows: install/windows.md
-                - Linux 🚧: install/linux.md
-                - MacOS 🚧: placeholder.md
+          - Unraid: install/unraid.md
+          - Windows: install/windows.md
+          - Linux: install/linux.md
+          - MacOS: install/macos.md
+          - FreeBSD: install/freebsd.md
     - User's Guide:
-          - Installing Apps 🚧: users/install_apps.md
+          - Getting Started: users/getting_started.md
+          - Installing Apps: users/install_apps.md
+          - Reverse Proxy: users/reverse_proxy.md
+          - Optimizations: users/optimizations.md
           - Configuring Conreq:
                 - Server Settings Interface: users/configure/server_settings.md
                 - Settings Config File: users/configure/env_vars.md
-                - Custom CSS/JS 🚧: users/configure/static_files.md
+                - Custom CSS/JS: users/configure/static_files.md
     - Developer's Guide:
           - Setup a Conreq Enviroment:
                 - 1. Install Requirements: developers/setup/requirements.md
                 - 2. Run Conreq from Source: developers/setup/run.md
-          - Programmer's Interface:
-                - Command Line Interface 🚧: developers/interface/cli.md
-                - Python Interface 🚧: developers/interface/python.md
+          - Command Line Interface: developers/interface/cli.md
+          - Python Interface:
+                - Front-End:
+                      - components: developers/interface/python/components.md
+                      - views: developers/interface/python/views.md
+                - Database & Forms:
+                      - forms: developers/interface/python/forms.md
+                      - fields: developers/interface/python/fields.md
+                      - models: developers/interface/python/models.md
+                      - validators: developers/interface/python/validators.md
+                      - widgets: developers/interface/python/widgets.md
+                - Startup Registration:
+                      - backup: developers/interface/python/register/backup.md
+                      - components: developers/interface/python/register/components.md
+                      - homepage: developers/interface/python/register/homepage.md
+                      - http: developers/interface/python/register/http.md
+                      - notifications: developers/interface/python/register/notifications.md
+                      - startup: developers/interface/python/register/startup.md
+                      - tabs: developers/interface/python/register/tabs.md
+                      - templates: developers/interface/python/register/templates.md
+                      - views: developers/interface/python/register/views.md
+                      - websockets: developers/interface/python/register/websockets.md
+                - Services:
+                      - email: developers/interface/python/services/email.md
           - Creating Your First App:
-                - Getting Started 🚧: developers/apps/getting_started.md
-                - App File Structure 🚧: developers/apps/file_structure.md
-                - Creating "Hello World" 🚧: developers/apps/hello_world.md
+                - Getting Started: developers/apps/getting_started.md
+                - App File Structure: developers/apps/file_structure.md
+                - Creating "Hello World": developers/apps/hello_world.md
           - Contributing:
-                - Conreq Source Code Explained 🚧: developers/contribute/code_tldr.md
-                - Updating Conreq Source Code 🚧: placeholder.md
+                - Conreq Source Code Explained: developers/contribute/code_tldr.md
+                - Updating Conreq Source Code: develoeprs/contribute/source.md
                 - Updating Conreq Docs: developers/contribute/docs.md
-                - Listing an App 🚧: developers/contribute/apps.md
+                - Listing an App: developers/contribute/apps.md
+    - Changelog: changelog/index.md
 
 theme:
     name: material