docs: Move docs-folder to root (#816)

* Move docs-folder form src to root

* Avoid mkdocs package / module name clash

* Update location of docs & add Windows compatibility

* Update requirements-docs

* Update generated file to current state

docs/README.md

@@ -3,4 +3,4 @@ title: Welcome to Django Components
 weight: 1
 ---
 <!-- NOTE: This README.md page is required, because it generates the top-level `index.html` -->
---8<-- "src/docs/overview/welcome.md:4"
+--8<-- "docs/overview/welcome.md:4"

docs/reference/commands.md

@@ -6,61 +6,19 @@ These are all the [Django management commands](https://docs.djangoproject.com/en
 that will be added by installing `django_components`:
 
 
-## `upgradecomponent`
-
-```txt
-usage: manage.py upgradecomponent [-h] [--path PATH] [--version] [-v {0,1,2,3}] [--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color]
-                                  [--force-color] [--skip-checks]
-
-```
-
-
-
-<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/management/commands/upgradecomponent.py#L12" target="_blank">See source code</a>
-
-
-
-Updates component and component_block tags to the new syntax
-
-**Options:**
-
-- `-h`, `--help`
-    - show this help message and exit
-- `--path PATH`
-    - Path to search for components
-- `--version`
-    - Show program's version number and exit.
-- `-v {0,1,2,3}`, `--verbosity {0,1,2,3}`
-    -  Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
-- `--settings SETTINGS`
-    - The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
-- `--pythonpath PYTHONPATH`
-    -  A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
-- `--traceback`
-    - Raise on CommandError exceptions.
-- `--no-color`
-    - Don't colorize the command output.
-- `--force-color`
-    - Force colorization of the command output.
-- `--skip-checks`
-    - Skip system checks.
-
-
-
-
-
 ## `startcomponent`
 
 ```txt
-usage: manage.py startcomponent [-h] [--path PATH] [--js JS] [--css CSS] [--template TEMPLATE] [--force] [--verbose] [--dry-run] [--version] [-v {0,1,2,3}]
+usage: manage.py startcomponent [-h] [--path PATH] [--js JS] [--css CSS] [--template TEMPLATE] [--force] [--verbose]
-                                [--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color] [--skip-checks]
+                                [--dry-run] [--version] [-v {0,1,2,3}] [--settings SETTINGS] [--pythonpath PYTHONPATH]
+                                [--traceback] [--no-color] [--force-color] [--skip-checks]
                                 name
 
 ```
 
 
 
-<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/management/commands/startcomponent.py#L8" target="_blank">See source code</a>
+<a href="https://github.com/EmilStenstrom/django-components/tree/master/src/django_components/management/commands/startcomponent.py#L8" target="_blank">See source code</a>
 
 
 
@@ -164,3 +122,46 @@ python manage.py startcomponent my_component --dry-run
 This will simulate the creation of `my_component` without creating any files.
 
 
+## `upgradecomponent`
+
+```txt
+usage: manage.py upgradecomponent [-h] [--path PATH] [--version] [-v {0,1,2,3}] [--settings SETTINGS]
+                                  [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color] [--skip-checks]
+
+```
+
+
+
+<a href="https://github.com/EmilStenstrom/django-components/tree/master/src/django_components/management/commands/upgradecomponent.py#L12" target="_blank">See source code</a>
+
+
+
+Updates component and component_block tags to the new syntax
+
+**Options:**
+
+- `-h`, `--help`
+    - show this help message and exit
+- `--path PATH`
+    - Path to search for components
+- `--version`
+    - Show program's version number and exit.
+- `-v {0,1,2,3}`, `--verbosity {0,1,2,3}`
+    -  Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
+- `--settings SETTINGS`
+    - The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
+- `--pythonpath PYTHONPATH`
+    -  A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
+- `--traceback`
+    - Raise on CommandError exceptions.
+- `--no-color`
+    - Don't colorize the command output.
+- `--force-color`
+    - Force colorization of the command output.
+- `--skip-checks`
+    - Skip system checks.
+
+
+
+
+

docs/reference/template_tags.md

@@ -21,7 +21,7 @@ Import as
 
 
 
-<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
+<a href="https://github.com/EmilStenstrom/django-components/tree/master/src/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
 
 
 
@@ -128,7 +128,7 @@ can access only the data that was explicitly passed to it:
 
 
 
-<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
+<a href="https://github.com/EmilStenstrom/django-components/tree/master/src/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
 
 
 
@@ -151,7 +151,7 @@ If you insert this tag multiple times, ALL CSS links will be duplicately inserte
 
 
 
-<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
+<a href="https://github.com/EmilStenstrom/django-components/tree/master/src/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
 
 
 
@@ -175,7 +175,7 @@ If you insert this tag multiple times, ALL JS scripts will be duplicately insert
 
 
 
-<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
+<a href="https://github.com/EmilStenstrom/django-components/tree/master/src/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
 
 
 
@@ -273,7 +273,7 @@ use `{% fill %}` with `name` set to `"default"`:
 
 
 
-<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
+<a href="https://github.com/EmilStenstrom/django-components/tree/master/src/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
 
 
 
@@ -336,7 +336,7 @@ renders
 
 
 
-<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
+<a href="https://github.com/EmilStenstrom/django-components/tree/master/src/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
 
 
 
@@ -416,7 +416,7 @@ user = self.inject("user_data")["user"]
 
 
 
-<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
+<a href="https://github.com/EmilStenstrom/django-components/tree/master/src/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
 
 
 

docs/scripts/extensions.py

@@ -2,9 +2,9 @@ from pathlib import Path
 from typing import List, Optional, Type
 
 import griffe
+from mkdocs_util import get_mkdocstrings_plugin_handler_options, import_object, load_config
 
 from django_components.util.misc import get_import_path
-from docs.scripts.mkdocs import get_mkdocstrings_plugin_handler_options, import_object, load_config
 
 SOURCE_CODE_GIT_BRANCH = "master"
 

docs/scripts/reference.py

@@ -36,7 +36,6 @@ we don't have to run it manually. It will be run each time mkdocs is built.
 """
 
 import inspect
-import os
 import re
 import sys
 from argparse import ArgumentParser
@@ -59,16 +58,14 @@ from django_components.util.misc import get_import_path
 #         - By default we can't do relative imports (e.g. `.extensions`)
 #         - We can't import from packages found in the `src` directory (e.g. `docs.scripts.extensions`)
 #
-#       But we need to import from another module.
+#       But we need to import from another module in ./docs/scripts.
-#       Hence we add the `src` directory to `sys.path` ourselves, so we can import from the
+#       Hence we add the directory of this file to `sys.path` ourselves.
-#       `docs.scripts.extensions` module.
-current_dir = os.path.dirname(os.path.abspath(__file__))
-src_dir = os.path.abspath(os.path.join(current_dir, "..", ".."))
-sys.path.insert(0, src_dir)
 
-from docs.scripts.extensions import _format_source_code_html  # noqa: E402
+current_dir = str(Path(__file__).parent)
+sys.path.append(current_dir)
+from extensions import _format_source_code_html  # noqa: E402
 
-root = Path(__file__).parent.parent.parent.parent
+root = Path(__file__).parent.parent.parent
 
 
 def gen_reference_api():
@@ -81,11 +78,11 @@ def gen_reference_api():
     module = import_module("django_components")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "src/docs/templates/reference_api.md").read_text()
+    preface += (root / "docs/templates/reference_api.md").read_text()
-    out_file = root / "src/docs/reference/api.md"
+    out_file = root / "docs/reference/api.md"
 
     out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w") as f:
+    with out_file.open("w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for name, obj in inspect.getmembers(module):
@@ -118,11 +115,11 @@ def gen_reference_exceptions():
     module = import_module("django_components")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "src/docs/templates/reference_exceptions.md").read_text()
+    preface += (root / "docs/templates/reference_exceptions.md").read_text()
-    out_file = root / "src/docs/reference/exceptions.md"
+    out_file = root / "docs/reference/exceptions.md"
 
     out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w") as f:
+    with out_file.open("w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for name, obj in inspect.getmembers(module):
@@ -153,11 +150,11 @@ def gen_reference_components():
     module = import_module("django_components.components")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "src/docs/templates/reference_components.md").read_text()
+    preface += (root / "docs/templates/reference_components.md").read_text()
-    out_file = root / "src/docs/reference/components.md"
+    out_file = root / "docs/reference/components.md"
 
     out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w") as f:
+    with out_file.open("w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for name, obj in inspect.getmembers(module):
@@ -203,11 +200,11 @@ def gen_reference_settings():
     module = import_module("django_components.app_settings")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "src/docs/templates/reference_settings.md").read_text()
+    preface += (root / "docs/templates/reference_settings.md").read_text()
-    out_file = root / "src/docs/reference/settings.md"
+    out_file = root / "docs/reference/settings.md"
 
     out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w") as f:
+    with out_file.open("w", encoding="utf-8") as f:
         # 1. Insert section from `reference_settings.md`
         f.write(preface + "\n\n")
 
@@ -260,7 +257,7 @@ def _get_unique_methods(base_class: Type, sub_class: Type):
 
 
 def _gen_default_settings_section(app_settings_filepath: str) -> str:
-    # In the soure code (`app_settings.py`), we've inserted following strings
+    # In the source code (`app_settings.py`), we've inserted following strings
     # to mark the start and end of the where we define the default settings.
     # We copy this as a plain string, so that the comments are preserved.
     settings_sourcecode = Path(app_settings_filepath).read_text()
@@ -308,11 +305,11 @@ def gen_reference_middlewares():
     module = import_module("django_components.middleware")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "src/docs/templates/reference_middlewares.md").read_text()
+    preface += (root / "docs/templates/reference_middlewares.md").read_text()
-    out_file = root / "src/docs/reference/middlewares.md"
+    out_file = root / "docs/reference/middlewares.md"
 
     out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w") as f:
+    with out_file.open("w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for name, obj in inspect.getmembers(module):
@@ -351,8 +348,8 @@ def gen_reference_tagformatters():
     module = import_module("django_components")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "src/docs/templates/reference_tagformatters.md").read_text()
+    preface += (root / "docs/templates/reference_tagformatters.md").read_text()
-    out_file = root / "src/docs/reference/tag_formatters.md"
+    out_file = root / "docs/reference/tag_formatters.md"
 
     tag_formatter_classes: Dict[str, Type[TagFormatterABC]] = {}
     tag_formatter_instances: Dict[str, TagFormatterABC] = {}
@@ -363,10 +360,10 @@ def gen_reference_tagformatters():
             tag_formatter_classes[name] = obj
 
     out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w") as f:
+    with out_file.open("w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
-        # Generate a summary of avilable tag formatters.
+        # Generate a summary of available tag formatters.
         # For each pre-defined TagFormatter entry, generate e.g.
         # ```markdown
         # - `django_components.component_formatter` for [ComponentFormatter](#django_components.ComponentFormatter)
@@ -414,13 +411,13 @@ def gen_reference_urls():
     module = import_module("django_components.urls")
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "src/docs/templates/reference_urls.md").read_text()
+    preface += (root / "docs/templates/reference_urls.md").read_text()
-    out_file = root / "src/docs/reference/urls.md"
+    out_file = root / "docs/reference/urls.md"
 
     all_urls = _list_urls(module.urlpatterns)
 
     out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w") as f:
+    with out_file.open("w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         # Simply list all URLs, e.g.
@@ -442,11 +439,11 @@ def gen_reference_commands():
     ]
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "src/docs/templates/reference_commands.md").read_text()
+    preface += (root / "docs/templates/reference_commands.md").read_text()
-    out_file = root / "src/docs/reference/commands.md"
+    out_file = root / "docs/reference/commands.md"
 
     out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w") as f:
+    with out_file.open("w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for cmd_name, cmd_path in command_modules:
@@ -459,7 +456,7 @@ def gen_reference_commands():
             formatted_args = _format_command_args(cmd_parser)
 
             # Add link to source code
-            module_rel_path = Path(cmd_module.__file__).relative_to(Path.cwd())  # type: ignore[arg-type]
+            module_rel_path = Path(cmd_module.__file__).relative_to(Path.cwd()).as_posix()  # type: ignore[arg-type]
             obj_lineno = inspect.findsource(cmd_cls)[1]
             source_code_link = _format_source_code_html(module_rel_path, obj_lineno)
 
@@ -490,16 +487,16 @@ def gen_reference_templatetags():
     ]
 
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "src/docs/templates/reference_templatetags.md").read_text()
+    preface += (root / "docs/templates/reference_templatetags.md").read_text()
-    out_file = root / "src/docs/reference/template_tags.md"
+    out_file = root / "docs/reference/template_tags.md"
 
     out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w") as f:
+    with out_file.open("w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for mod_name, mod_path in tags_modules:
             tags_module = import_module(mod_path)
-            module_rel_path = Path(tags_module.__file__).relative_to(Path.cwd())  # type: ignore[arg-type]
+            module_rel_path = Path(tags_module.__file__).relative_to(Path.cwd()).as_posix()  # type: ignore[arg-type]
 
             f.write(
                 f"All following template tags are defined in\n\n"
@@ -543,11 +540,11 @@ def gen_reference_templatevars():
     under the `{{ component_vars }}` variable, as defined by `ComponentVars`.
     """
     preface = "<!-- Autogenerated by reference.py -->\n\n"
-    preface += (root / "src/docs/templates/reference_templatevars.md").read_text()
+    preface += (root / "docs/templates/reference_templatevars.md").read_text()
-    out_file = root / "src/docs/reference/template_vars.md"
+    out_file = root / "docs/reference/template_vars.md"
 
     out_file.parent.mkdir(parents=True, exist_ok=True)
-    with out_file.open("w") as f:
+    with out_file.open("w", encoding="utf-8") as f:
         f.write(preface + "\n\n")
 
         for field in ComponentVars._fields:

mkdocs.yml

@@ -5,14 +5,15 @@ site_url: https://emilstenstrom.github.io/django-components/
 
 repo_url: https://github.com/EmilStenstrom/django-components
 repo_name: EmilStenstrom/django-components
-edit_uri: https://github.com/EmilStenstrom/django-components/edit/master/src/docs/
+edit_uri: https://github.com/EmilStenstrom/django-components/edit/master/docs/
 
 dev_addr: "127.0.0.1:9000"
 site_dir: site
-docs_dir: src/docs
+docs_dir: docs
 
 watch:
   - src
+  - docs
   - mkdocs.yml
   - README.md
   - CHANGELOG.md
@@ -26,7 +27,7 @@ validation:
 
 theme:
   name: "material"
-  custom_dir: src/docs/overrides
+  custom_dir: docs/overrides
   features:
     - content.action.edit
     - content.action.view
@@ -121,7 +122,7 @@ plugins:
       closing_tag: "!}"
   - gen-files:
       scripts:
-        - src/docs/scripts/reference.py
+        - docs/scripts/reference.py
   - literate-nav:
       nav_file: SUMMARY.md
       tab_length: 2
@@ -189,5 +190,5 @@ plugins:
             show_source: false # NOTE: Instead we use SourceCodeExtension
             # NOTE: Order matters!
             extensions:
-            - src/docs/scripts/extensions.py:RuntimeBasesExtension
+            - docs/scripts/extensions.py:RuntimeBasesExtension
-            - src/docs/scripts/extensions.py:SourceCodeExtension
+            - docs/scripts/extensions.py:SourceCodeExtension

requirements-docs.txt

@@ -13,12 +13,14 @@
 # - mkdocs-material
 # - mkdocs-material[imaging]
 # - mkdocs-minify-plugin
+# - mkdocs-nav-weight
 # - mkdocs-redirects
 # - mkdocstrings
 # - mkdocstrings-python
 # - pymdown-extensions
 # - black
 # - django>=4.2
+# - selectolax>=0.3.24
 #
 
 asgiref==3.8.1
@@ -48,7 +50,9 @@ click==8.1.7
     #   mkdocstrings
 colorama==0.4.6
     # via
+    #   click
     #   griffe
+    #   mkdocs
     #   mkdocs-material
 csscompressor==0.9.5
     # via mkdocs-minify-plugin
@@ -115,6 +119,7 @@ mkdocs==1.6.1
     #   mkdocs-literate-nav
     #   mkdocs-material
     #   mkdocs-minify-plugin
+    #   mkdocs-nav-weight
     #   mkdocs-redirects
     #   mkdocstrings
 mkdocs-autorefs==1.2.0
@@ -141,7 +146,7 @@ mkdocs-material-extensions==1.3.1
 mkdocs-minify-plugin==0.8.0
     # via hatch.envs.docs
 mkdocs-nav-weight==0.2.0
-    # manually added
+    # via hatch.envs.docs
 mkdocs-redirects==1.2.2
     # via hatch.envs.docs
 mkdocstrings==0.27.0
@@ -162,7 +167,7 @@ pathspec==0.12.1
     # via
     #   black
     #   mkdocs
-pillow==11.0.0
+pillow==10.4.0
     # via
     #   cairosvg
     #   mkdocs-material
@@ -202,6 +207,8 @@ regex==2024.11.6
     # via mkdocs-material
 requests==2.32.3
     # via mkdocs-material
+selectolax==0.3.26
+    # via hatch.envs.docs
 six==1.16.0
     # via python-dateutil
 smmap==5.0.1
@@ -212,6 +219,8 @@ tinycss2==1.4.0
     # via
     #   cairosvg
     #   cssselect2
+tzdata==2024.2
+    # via django
 urllib3==2.2.3
     # via requests
 verspec==0.1.0

scripts/supported_versions.py

@@ -264,13 +264,13 @@ def main():
     print()
     print()
 
-    print("Add this to src/docs/overview/compatibility.md:\n")
+    print("Add this to docs/overview/compatibility.md:\n")
     readme = build_readme(python_to_django)
     print(readme)
     print()
     print()
 
-    print("Add this to src/docs/overview/development.md:\n")
+    print("Add this to docs/overview/development.md:\n")
     pyenv = build_pyenv(python_to_django)
     print(pyenv)
     print()