From 594c0689bae2ae4729fca0c4d90abf3adab52733 Mon Sep 17 00:00:00 2001 From: David Linke Date: Tue, 3 Dec 2024 12:32:21 +0100 Subject: [PATCH] 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 --- {src/docs => docs}/README.md | 2 +- {src/docs => docs}/SUMMARY.md | 0 {src/docs => docs}/__init__.py | 0 .../advanced/authoring_component_libraries.md | 0 .../concepts/advanced/component_registry.md | 0 {src/docs => docs}/concepts/advanced/hooks.md | 0 .../concepts/advanced/provide_inject.md | 0 .../concepts/advanced/rendering_js_css.md | 0 .../concepts/advanced/tag_formatter.md | 0 .../advanced/typing_and_validation.md | 0 .../fundamentals/access_component_input.md | 0 .../concepts/fundamentals/autodiscovery.md | 0 .../fundamentals/component_context_scope.md | 0 .../fundamentals/components_as_views.md | 0 .../fundamentals/components_in_python.md | 0 .../fundamentals/components_in_templates.md | 0 .../defining_js_css_html_files.md | 0 .../concepts/fundamentals/html_attributes.md | 0 .../fundamentals/single_file_components.md | 0 .../concepts/fundamentals/slots.md | 0 .../fundamentals/template_tag_syntax.md | 0 .../fundamentals/your_first_component.md | 0 {src/docs => docs}/css/style.css | 0 .../devguides/dependency_mgmt.md | 0 .../docs => docs}/devguides/slot_rendering.md | 0 .../devguides/slots_and_blocks.md | 0 .../guides/setup/dev_server_setup.md | 0 .../guides/setup/logging_and_debugging.md | 0 .../guides/setup/syntax_highlight.md | 0 .../migrating_from_safer_staticfiles.md | 0 {src/docs => docs}/overrides/main.html | 0 .../docs => docs}/overview/code_of_conduct.md | 0 {src/docs => docs}/overview/community.md | 0 {src/docs => docs}/overview/compatibility.md | 0 {src/docs => docs}/overview/contributing.md | 0 {src/docs => docs}/overview/development.md | 0 {src/docs => docs}/overview/installation.md | 0 {src/docs => docs}/overview/license.md | 0 {src/docs => docs}/overview/security_notes.md | 0 {src/docs => docs}/overview/welcome.md | 0 {src/docs => docs}/reference/api.md | 0 {src/docs => docs}/reference/commands.md | 93 ++++++++++--------- {src/docs => docs}/reference/components.md | 0 {src/docs => docs}/reference/exceptions.md | 0 {src/docs => docs}/reference/middlewares.md | 0 {src/docs => docs}/reference/settings.md | 0 .../docs => docs}/reference/tag_formatters.md | 0 {src/docs => docs}/reference/template_tags.md | 14 +-- {src/docs => docs}/reference/template_vars.md | 0 {src/docs => docs}/reference/urls.md | 0 {src/docs => docs}/release_notes.md | 0 {src/docs => docs}/scripts/__init__.py | 0 {src/docs => docs}/scripts/extensions.py | 2 +- .../mkdocs.py => docs/scripts/mkdocs_util.py | 0 {src/docs => docs}/scripts/reference.py | 83 ++++++++--------- {src/docs => docs}/templates/reference_api.md | 0 .../templates/reference_commands.md | 0 .../templates/reference_components.md | 0 .../templates/reference_exceptions.md | 0 .../templates/reference_middlewares.md | 0 .../templates/reference_settings.md | 0 .../templates/reference_tagformatters.md | 0 .../templates/reference_templatetags.md | 0 .../templates/reference_templatevars.md | 0 .../docs => docs}/templates/reference_urls.md | 0 mkdocs.yml | 13 +-- requirements-docs.txt | 13 ++- scripts/supported_versions.py | 4 +- 68 files changed, 116 insertions(+), 108 deletions(-) rename {src/docs => docs}/README.md (78%) rename {src/docs => docs}/SUMMARY.md (100%) rename {src/docs => docs}/__init__.py (100%) rename {src/docs => docs}/concepts/advanced/authoring_component_libraries.md (100%) rename {src/docs => docs}/concepts/advanced/component_registry.md (100%) rename {src/docs => docs}/concepts/advanced/hooks.md (100%) rename {src/docs => docs}/concepts/advanced/provide_inject.md (100%) rename {src/docs => docs}/concepts/advanced/rendering_js_css.md (100%) rename {src/docs => docs}/concepts/advanced/tag_formatter.md (100%) rename {src/docs => docs}/concepts/advanced/typing_and_validation.md (100%) rename {src/docs => docs}/concepts/fundamentals/access_component_input.md (100%) rename {src/docs => docs}/concepts/fundamentals/autodiscovery.md (100%) rename {src/docs => docs}/concepts/fundamentals/component_context_scope.md (100%) rename {src/docs => docs}/concepts/fundamentals/components_as_views.md (100%) rename {src/docs => docs}/concepts/fundamentals/components_in_python.md (100%) rename {src/docs => docs}/concepts/fundamentals/components_in_templates.md (100%) rename {src/docs => docs}/concepts/fundamentals/defining_js_css_html_files.md (100%) rename {src/docs => docs}/concepts/fundamentals/html_attributes.md (100%) rename {src/docs => docs}/concepts/fundamentals/single_file_components.md (100%) rename {src/docs => docs}/concepts/fundamentals/slots.md (100%) rename {src/docs => docs}/concepts/fundamentals/template_tag_syntax.md (100%) rename {src/docs => docs}/concepts/fundamentals/your_first_component.md (100%) rename {src/docs => docs}/css/style.css (100%) rename {src/docs => docs}/devguides/dependency_mgmt.md (100%) rename {src/docs => docs}/devguides/slot_rendering.md (100%) rename {src/docs => docs}/devguides/slots_and_blocks.md (100%) rename {src/docs => docs}/guides/setup/dev_server_setup.md (100%) rename {src/docs => docs}/guides/setup/logging_and_debugging.md (100%) rename {src/docs => docs}/guides/setup/syntax_highlight.md (100%) rename {src/docs => docs}/migrating_from_safer_staticfiles.md (100%) rename {src/docs => docs}/overrides/main.html (100%) rename {src/docs => docs}/overview/code_of_conduct.md (100%) rename {src/docs => docs}/overview/community.md (100%) rename {src/docs => docs}/overview/compatibility.md (100%) rename {src/docs => docs}/overview/contributing.md (100%) rename {src/docs => docs}/overview/development.md (100%) rename {src/docs => docs}/overview/installation.md (100%) rename {src/docs => docs}/overview/license.md (100%) rename {src/docs => docs}/overview/security_notes.md (100%) rename {src/docs => docs}/overview/welcome.md (100%) rename {src/docs => docs}/reference/api.md (100%) rename {src/docs => docs}/reference/commands.md (88%) rename {src/docs => docs}/reference/components.md (100%) rename {src/docs => docs}/reference/exceptions.md (100%) rename {src/docs => docs}/reference/middlewares.md (100%) rename {src/docs => docs}/reference/settings.md (100%) rename {src/docs => docs}/reference/tag_formatters.md (100%) rename {src/docs => docs}/reference/template_tags.md (93%) rename {src/docs => docs}/reference/template_vars.md (100%) rename {src/docs => docs}/reference/urls.md (100%) rename {src/docs => docs}/release_notes.md (100%) rename {src/docs => docs}/scripts/__init__.py (100%) rename {src/docs => docs}/scripts/extensions.py (95%) rename src/docs/scripts/mkdocs.py => docs/scripts/mkdocs_util.py (100%) rename {src/docs => docs}/scripts/reference.py (91%) rename {src/docs => docs}/templates/reference_api.md (100%) rename {src/docs => docs}/templates/reference_commands.md (100%) rename {src/docs => docs}/templates/reference_components.md (100%) rename {src/docs => docs}/templates/reference_exceptions.md (100%) rename {src/docs => docs}/templates/reference_middlewares.md (100%) rename {src/docs => docs}/templates/reference_settings.md (100%) rename {src/docs => docs}/templates/reference_tagformatters.md (100%) rename {src/docs => docs}/templates/reference_templatetags.md (100%) rename {src/docs => docs}/templates/reference_templatevars.md (100%) rename {src/docs => docs}/templates/reference_urls.md (100%) diff --git a/src/docs/README.md b/docs/README.md similarity index 78% rename from src/docs/README.md rename to docs/README.md index e63ecd2d..74b225f9 100644 --- a/src/docs/README.md +++ b/docs/README.md @@ -3,4 +3,4 @@ title: Welcome to Django Components weight: 1 --- ---8<-- "src/docs/overview/welcome.md:4" +--8<-- "docs/overview/welcome.md:4" diff --git a/src/docs/SUMMARY.md b/docs/SUMMARY.md similarity index 100% rename from src/docs/SUMMARY.md rename to docs/SUMMARY.md diff --git a/src/docs/__init__.py b/docs/__init__.py similarity index 100% rename from src/docs/__init__.py rename to docs/__init__.py diff --git a/src/docs/concepts/advanced/authoring_component_libraries.md b/docs/concepts/advanced/authoring_component_libraries.md similarity index 100% rename from src/docs/concepts/advanced/authoring_component_libraries.md rename to docs/concepts/advanced/authoring_component_libraries.md diff --git a/src/docs/concepts/advanced/component_registry.md b/docs/concepts/advanced/component_registry.md similarity index 100% rename from src/docs/concepts/advanced/component_registry.md rename to docs/concepts/advanced/component_registry.md diff --git a/src/docs/concepts/advanced/hooks.md b/docs/concepts/advanced/hooks.md similarity index 100% rename from src/docs/concepts/advanced/hooks.md rename to docs/concepts/advanced/hooks.md diff --git a/src/docs/concepts/advanced/provide_inject.md b/docs/concepts/advanced/provide_inject.md similarity index 100% rename from src/docs/concepts/advanced/provide_inject.md rename to docs/concepts/advanced/provide_inject.md diff --git a/src/docs/concepts/advanced/rendering_js_css.md b/docs/concepts/advanced/rendering_js_css.md similarity index 100% rename from src/docs/concepts/advanced/rendering_js_css.md rename to docs/concepts/advanced/rendering_js_css.md diff --git a/src/docs/concepts/advanced/tag_formatter.md b/docs/concepts/advanced/tag_formatter.md similarity index 100% rename from src/docs/concepts/advanced/tag_formatter.md rename to docs/concepts/advanced/tag_formatter.md diff --git a/src/docs/concepts/advanced/typing_and_validation.md b/docs/concepts/advanced/typing_and_validation.md similarity index 100% rename from src/docs/concepts/advanced/typing_and_validation.md rename to docs/concepts/advanced/typing_and_validation.md diff --git a/src/docs/concepts/fundamentals/access_component_input.md b/docs/concepts/fundamentals/access_component_input.md similarity index 100% rename from src/docs/concepts/fundamentals/access_component_input.md rename to docs/concepts/fundamentals/access_component_input.md diff --git a/src/docs/concepts/fundamentals/autodiscovery.md b/docs/concepts/fundamentals/autodiscovery.md similarity index 100% rename from src/docs/concepts/fundamentals/autodiscovery.md rename to docs/concepts/fundamentals/autodiscovery.md diff --git a/src/docs/concepts/fundamentals/component_context_scope.md b/docs/concepts/fundamentals/component_context_scope.md similarity index 100% rename from src/docs/concepts/fundamentals/component_context_scope.md rename to docs/concepts/fundamentals/component_context_scope.md diff --git a/src/docs/concepts/fundamentals/components_as_views.md b/docs/concepts/fundamentals/components_as_views.md similarity index 100% rename from src/docs/concepts/fundamentals/components_as_views.md rename to docs/concepts/fundamentals/components_as_views.md diff --git a/src/docs/concepts/fundamentals/components_in_python.md b/docs/concepts/fundamentals/components_in_python.md similarity index 100% rename from src/docs/concepts/fundamentals/components_in_python.md rename to docs/concepts/fundamentals/components_in_python.md diff --git a/src/docs/concepts/fundamentals/components_in_templates.md b/docs/concepts/fundamentals/components_in_templates.md similarity index 100% rename from src/docs/concepts/fundamentals/components_in_templates.md rename to docs/concepts/fundamentals/components_in_templates.md diff --git a/src/docs/concepts/fundamentals/defining_js_css_html_files.md b/docs/concepts/fundamentals/defining_js_css_html_files.md similarity index 100% rename from src/docs/concepts/fundamentals/defining_js_css_html_files.md rename to docs/concepts/fundamentals/defining_js_css_html_files.md diff --git a/src/docs/concepts/fundamentals/html_attributes.md b/docs/concepts/fundamentals/html_attributes.md similarity index 100% rename from src/docs/concepts/fundamentals/html_attributes.md rename to docs/concepts/fundamentals/html_attributes.md diff --git a/src/docs/concepts/fundamentals/single_file_components.md b/docs/concepts/fundamentals/single_file_components.md similarity index 100% rename from src/docs/concepts/fundamentals/single_file_components.md rename to docs/concepts/fundamentals/single_file_components.md diff --git a/src/docs/concepts/fundamentals/slots.md b/docs/concepts/fundamentals/slots.md similarity index 100% rename from src/docs/concepts/fundamentals/slots.md rename to docs/concepts/fundamentals/slots.md diff --git a/src/docs/concepts/fundamentals/template_tag_syntax.md b/docs/concepts/fundamentals/template_tag_syntax.md similarity index 100% rename from src/docs/concepts/fundamentals/template_tag_syntax.md rename to docs/concepts/fundamentals/template_tag_syntax.md diff --git a/src/docs/concepts/fundamentals/your_first_component.md b/docs/concepts/fundamentals/your_first_component.md similarity index 100% rename from src/docs/concepts/fundamentals/your_first_component.md rename to docs/concepts/fundamentals/your_first_component.md diff --git a/src/docs/css/style.css b/docs/css/style.css similarity index 100% rename from src/docs/css/style.css rename to docs/css/style.css diff --git a/src/docs/devguides/dependency_mgmt.md b/docs/devguides/dependency_mgmt.md similarity index 100% rename from src/docs/devguides/dependency_mgmt.md rename to docs/devguides/dependency_mgmt.md diff --git a/src/docs/devguides/slot_rendering.md b/docs/devguides/slot_rendering.md similarity index 100% rename from src/docs/devguides/slot_rendering.md rename to docs/devguides/slot_rendering.md diff --git a/src/docs/devguides/slots_and_blocks.md b/docs/devguides/slots_and_blocks.md similarity index 100% rename from src/docs/devguides/slots_and_blocks.md rename to docs/devguides/slots_and_blocks.md diff --git a/src/docs/guides/setup/dev_server_setup.md b/docs/guides/setup/dev_server_setup.md similarity index 100% rename from src/docs/guides/setup/dev_server_setup.md rename to docs/guides/setup/dev_server_setup.md diff --git a/src/docs/guides/setup/logging_and_debugging.md b/docs/guides/setup/logging_and_debugging.md similarity index 100% rename from src/docs/guides/setup/logging_and_debugging.md rename to docs/guides/setup/logging_and_debugging.md diff --git a/src/docs/guides/setup/syntax_highlight.md b/docs/guides/setup/syntax_highlight.md similarity index 100% rename from src/docs/guides/setup/syntax_highlight.md rename to docs/guides/setup/syntax_highlight.md diff --git a/src/docs/migrating_from_safer_staticfiles.md b/docs/migrating_from_safer_staticfiles.md similarity index 100% rename from src/docs/migrating_from_safer_staticfiles.md rename to docs/migrating_from_safer_staticfiles.md diff --git a/src/docs/overrides/main.html b/docs/overrides/main.html similarity index 100% rename from src/docs/overrides/main.html rename to docs/overrides/main.html diff --git a/src/docs/overview/code_of_conduct.md b/docs/overview/code_of_conduct.md similarity index 100% rename from src/docs/overview/code_of_conduct.md rename to docs/overview/code_of_conduct.md diff --git a/src/docs/overview/community.md b/docs/overview/community.md similarity index 100% rename from src/docs/overview/community.md rename to docs/overview/community.md diff --git a/src/docs/overview/compatibility.md b/docs/overview/compatibility.md similarity index 100% rename from src/docs/overview/compatibility.md rename to docs/overview/compatibility.md diff --git a/src/docs/overview/contributing.md b/docs/overview/contributing.md similarity index 100% rename from src/docs/overview/contributing.md rename to docs/overview/contributing.md diff --git a/src/docs/overview/development.md b/docs/overview/development.md similarity index 100% rename from src/docs/overview/development.md rename to docs/overview/development.md diff --git a/src/docs/overview/installation.md b/docs/overview/installation.md similarity index 100% rename from src/docs/overview/installation.md rename to docs/overview/installation.md diff --git a/src/docs/overview/license.md b/docs/overview/license.md similarity index 100% rename from src/docs/overview/license.md rename to docs/overview/license.md diff --git a/src/docs/overview/security_notes.md b/docs/overview/security_notes.md similarity index 100% rename from src/docs/overview/security_notes.md rename to docs/overview/security_notes.md diff --git a/src/docs/overview/welcome.md b/docs/overview/welcome.md similarity index 100% rename from src/docs/overview/welcome.md rename to docs/overview/welcome.md diff --git a/src/docs/reference/api.md b/docs/reference/api.md similarity index 100% rename from src/docs/reference/api.md rename to docs/reference/api.md diff --git a/src/docs/reference/commands.md b/docs/reference/commands.md similarity index 88% rename from src/docs/reference/commands.md rename to docs/reference/commands.md index 73979ece..8bbbe7ca 100644 --- a/src/docs/reference/commands.md +++ b/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] - -``` - - - -See source code - - - -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}] - [--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color] [--skip-checks] +usage: manage.py startcomponent [-h] [--path PATH] [--js JS] [--css CSS] [--template TEMPLATE] [--force] [--verbose] + [--dry-run] [--version] [-v {0,1,2,3}] [--settings SETTINGS] [--pythonpath PYTHONPATH] + [--traceback] [--no-color] [--force-color] [--skip-checks] name ``` -See source code +See source code @@ -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] + +``` + + + +See source code + + + +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. + + + + + diff --git a/src/docs/reference/components.md b/docs/reference/components.md similarity index 100% rename from src/docs/reference/components.md rename to docs/reference/components.md diff --git a/src/docs/reference/exceptions.md b/docs/reference/exceptions.md similarity index 100% rename from src/docs/reference/exceptions.md rename to docs/reference/exceptions.md diff --git a/src/docs/reference/middlewares.md b/docs/reference/middlewares.md similarity index 100% rename from src/docs/reference/middlewares.md rename to docs/reference/middlewares.md diff --git a/src/docs/reference/settings.md b/docs/reference/settings.md similarity index 100% rename from src/docs/reference/settings.md rename to docs/reference/settings.md diff --git a/src/docs/reference/tag_formatters.md b/docs/reference/tag_formatters.md similarity index 100% rename from src/docs/reference/tag_formatters.md rename to docs/reference/tag_formatters.md diff --git a/src/docs/reference/template_tags.md b/docs/reference/template_tags.md similarity index 93% rename from src/docs/reference/template_tags.md rename to docs/reference/template_tags.md index 933624f7..53ae3992 100644 --- a/src/docs/reference/template_tags.md +++ b/docs/reference/template_tags.md @@ -21,7 +21,7 @@ Import as -See source code +See source code @@ -128,7 +128,7 @@ can access only the data that was explicitly passed to it: -See source code +See source code @@ -151,7 +151,7 @@ If you insert this tag multiple times, ALL CSS links will be duplicately inserte -See source code +See source code @@ -175,7 +175,7 @@ If you insert this tag multiple times, ALL JS scripts will be duplicately insert -See source code +See source code @@ -273,7 +273,7 @@ use `{% fill %}` with `name` set to `"default"`: -See source code +See source code @@ -336,7 +336,7 @@ renders -See source code +See source code @@ -416,7 +416,7 @@ user = self.inject("user_data")["user"] -See source code +See source code diff --git a/src/docs/reference/template_vars.md b/docs/reference/template_vars.md similarity index 100% rename from src/docs/reference/template_vars.md rename to docs/reference/template_vars.md diff --git a/src/docs/reference/urls.md b/docs/reference/urls.md similarity index 100% rename from src/docs/reference/urls.md rename to docs/reference/urls.md diff --git a/src/docs/release_notes.md b/docs/release_notes.md similarity index 100% rename from src/docs/release_notes.md rename to docs/release_notes.md diff --git a/src/docs/scripts/__init__.py b/docs/scripts/__init__.py similarity index 100% rename from src/docs/scripts/__init__.py rename to docs/scripts/__init__.py diff --git a/src/docs/scripts/extensions.py b/docs/scripts/extensions.py similarity index 95% rename from src/docs/scripts/extensions.py rename to docs/scripts/extensions.py index b7fbf26c..7197d85b 100644 --- a/src/docs/scripts/extensions.py +++ b/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" diff --git a/src/docs/scripts/mkdocs.py b/docs/scripts/mkdocs_util.py similarity index 100% rename from src/docs/scripts/mkdocs.py rename to docs/scripts/mkdocs_util.py diff --git a/src/docs/scripts/reference.py b/docs/scripts/reference.py similarity index 91% rename from src/docs/scripts/reference.py rename to docs/scripts/reference.py index bd85145c..57461fab 100644 --- a/src/docs/scripts/reference.py +++ b/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. -# Hence we add the `src` directory to `sys.path` ourselves, so we can import from the -# `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) +# But we need to import from another module in ./docs/scripts. +# Hence we add the directory of this file to `sys.path` ourselves. -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 = "\n\n" - preface += (root / "src/docs/templates/reference_api.md").read_text() - out_file = root / "src/docs/reference/api.md" + preface += (root / "docs/templates/reference_api.md").read_text() + 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 = "\n\n" - preface += (root / "src/docs/templates/reference_exceptions.md").read_text() - out_file = root / "src/docs/reference/exceptions.md" + preface += (root / "docs/templates/reference_exceptions.md").read_text() + 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 = "\n\n" - preface += (root / "src/docs/templates/reference_components.md").read_text() - out_file = root / "src/docs/reference/components.md" + preface += (root / "docs/templates/reference_components.md").read_text() + 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 = "\n\n" - preface += (root / "src/docs/templates/reference_settings.md").read_text() - out_file = root / "src/docs/reference/settings.md" + preface += (root / "docs/templates/reference_settings.md").read_text() + 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 = "\n\n" - preface += (root / "src/docs/templates/reference_middlewares.md").read_text() - out_file = root / "src/docs/reference/middlewares.md" + preface += (root / "docs/templates/reference_middlewares.md").read_text() + 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 = "\n\n" - preface += (root / "src/docs/templates/reference_tagformatters.md").read_text() - out_file = root / "src/docs/reference/tag_formatters.md" + preface += (root / "docs/templates/reference_tagformatters.md").read_text() + 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 = "\n\n" - preface += (root / "src/docs/templates/reference_urls.md").read_text() - out_file = root / "src/docs/reference/urls.md" + preface += (root / "docs/templates/reference_urls.md").read_text() + 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 = "\n\n" - preface += (root / "src/docs/templates/reference_commands.md").read_text() - out_file = root / "src/docs/reference/commands.md" + preface += (root / "docs/templates/reference_commands.md").read_text() + 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 = "\n\n" - preface += (root / "src/docs/templates/reference_templatetags.md").read_text() - out_file = root / "src/docs/reference/template_tags.md" + preface += (root / "docs/templates/reference_templatetags.md").read_text() + 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 = "\n\n" - preface += (root / "src/docs/templates/reference_templatevars.md").read_text() - out_file = root / "src/docs/reference/template_vars.md" + preface += (root / "docs/templates/reference_templatevars.md").read_text() + 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: diff --git a/src/docs/templates/reference_api.md b/docs/templates/reference_api.md similarity index 100% rename from src/docs/templates/reference_api.md rename to docs/templates/reference_api.md diff --git a/src/docs/templates/reference_commands.md b/docs/templates/reference_commands.md similarity index 100% rename from src/docs/templates/reference_commands.md rename to docs/templates/reference_commands.md diff --git a/src/docs/templates/reference_components.md b/docs/templates/reference_components.md similarity index 100% rename from src/docs/templates/reference_components.md rename to docs/templates/reference_components.md diff --git a/src/docs/templates/reference_exceptions.md b/docs/templates/reference_exceptions.md similarity index 100% rename from src/docs/templates/reference_exceptions.md rename to docs/templates/reference_exceptions.md diff --git a/src/docs/templates/reference_middlewares.md b/docs/templates/reference_middlewares.md similarity index 100% rename from src/docs/templates/reference_middlewares.md rename to docs/templates/reference_middlewares.md diff --git a/src/docs/templates/reference_settings.md b/docs/templates/reference_settings.md similarity index 100% rename from src/docs/templates/reference_settings.md rename to docs/templates/reference_settings.md diff --git a/src/docs/templates/reference_tagformatters.md b/docs/templates/reference_tagformatters.md similarity index 100% rename from src/docs/templates/reference_tagformatters.md rename to docs/templates/reference_tagformatters.md diff --git a/src/docs/templates/reference_templatetags.md b/docs/templates/reference_templatetags.md similarity index 100% rename from src/docs/templates/reference_templatetags.md rename to docs/templates/reference_templatetags.md diff --git a/src/docs/templates/reference_templatevars.md b/docs/templates/reference_templatevars.md similarity index 100% rename from src/docs/templates/reference_templatevars.md rename to docs/templates/reference_templatevars.md diff --git a/src/docs/templates/reference_urls.md b/docs/templates/reference_urls.md similarity index 100% rename from src/docs/templates/reference_urls.md rename to docs/templates/reference_urls.md diff --git a/mkdocs.yml b/mkdocs.yml index bb83b9fc..f2ebd1a4 100644 --- a/mkdocs.yml +++ b/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 - - src/docs/scripts/extensions.py:SourceCodeExtension + - docs/scripts/extensions.py:RuntimeBasesExtension + - docs/scripts/extensions.py:SourceCodeExtension diff --git a/requirements-docs.txt b/requirements-docs.txt index cdcc8953..1327c79e 100644 --- a/requirements-docs.txt +++ b/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 diff --git a/scripts/supported_versions.py b/scripts/supported_versions.py index 992d3ff3..3f366a36 100644 --- a/scripts/supported_versions.py +++ b/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()