From 4efff28210b60bb02274410511dc7bc0c18cc400 Mon Sep 17 00:00:00 2001 From: Michaelyin Date: Mon, 26 Aug 2024 22:08:42 +0800 Subject: [PATCH] chore --- CHANGELOG.md | 1 + docs/Makefile | 20 +++++++++ docs/make.bat | 35 ++++++++++++++++ docs/requirements.txt | 2 + docs/source/conf.py | 76 ++++++++++++++++++++++++++++++++++ docs/source/getting_started.md | 57 +++++++++++++++++++++++++ docs/source/index.rst | 12 ++++++ docs/source/install.md | 14 +++++++ 8 files changed, 217 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt create mode 100644 docs/source/conf.py create mode 100644 docs/source/getting_started.md create mode 100644 docs/source/index.rst create mode 100644 docs/source/install.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..825c32f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1 @@ +# Changelog diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..de8c25c --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +furo==2023.9.10 +myst-parser diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..2bd0d6b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,76 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +import datetime +import sys +import tomllib +from pathlib import Path + +here = Path(__file__).parent.resolve() +sys.path.insert(0, str(here / ".." / ".." / "src")) + + +# -- Project information ----------------------------------------------------- +project = "django-template-simplify" +copyright = f"{datetime.datetime.now().year}, Michael Yin" +author = "Michael Yin" + + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. + + +def _get_version() -> str: + with (here / ".." / ".." / "pyproject.toml").open("rb") as fp: + data = tomllib.load(fp) + version: str = data["tool"]["poetry"]["version"] + return version + + +version = _get_version() +# The full version, including alpha/beta/rc tags. +release = version + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.autodoc", "myst_parser"] + +source_suffix = { + ".rst": "restructuredtext", + ".txt": "markdown", + ".md": "markdown", +} + +templates_path = ["_templates"] +exclude_patterns = [] # type: ignore + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +# html_theme = 'alabaster' +# html_static_path = ['_static'] +html_theme = "furo" +pygments_style = "sphinx" + +announcement_html = """ +
+ Have questions, feedback, or just want to chat? Reach out to me on + + Twitter / X + +
+""" + +html_theme_options = { + "announcement": announcement_html, +} diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md new file mode 100644 index 0000000..35ee161 --- /dev/null +++ b/docs/source/getting_started.md @@ -0,0 +1,57 @@ +# Getting Started + +```shell +$ pip install django-template-simplify +``` + +Then add the app into `INSTALLED_APPS` in settings.py + +```python +INSTALLED_APPS = [ + ..., + 'template_simplify', +] +``` + +## dom_id + +`dom_id` is a helper method that returns a unique DOM ID based on the object's class name and primary key. + +```html +{% load template_simplify %} + +{% dom_id instance %} -> task_1 +{% dom_id instance 'detail' %} -> detail_task_1 +{% dom_id Task %} -> new_task +``` + +1. `dom_id` first argument can be string, instance or Model class +2. `dom_id` second argument is optional string that will be used as `prefix`. + +You can also use it in your Django view code. + +```python +from template_simplify import dom_id + +target = dom_id(instance, "detail_container") +``` + +We can say goodbye to `id="task-{{ task.pk }}"` and use `id="{% dom_id task %}"` instead. + +The benefit is, **it simplified the DOM ID generation in Python and Django template, and avoid typo error in many cases.** + +## class_names + +Inspired by JS [classnames](https://www.npmjs.com/package/classnames) and Rails `class_names` + +`class_names` can help **conditionally render css classes** + +```html +{% load template_simplify %} + +
+ +'
' +``` + +It can also work well with TailwindCSS's some special char such as `/` and `:` diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..488a739 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,12 @@ +django-template-simplify +===================== + +A set of tools to help simplify your Django templates. + +Topics +------ + +.. toctree:: + :maxdepth: 2 + + getting_started.md diff --git a/docs/source/install.md b/docs/source/install.md new file mode 100644 index 0000000..0c2bc75 --- /dev/null +++ b/docs/source/install.md @@ -0,0 +1,14 @@ +# Installation + +```shell +$ pip install django-template-simplify +``` + +Then add the app into `INSTALLED_APPS` in settings.py + +```python +INSTALLED_APPS = [ + ..., + 'template_simplify', +] +```