docs: wip

Author: liborjelinek

docs/source/_static/preview-mixed-output.png

@@ -0,0 +1,10 @@
+# Features
+
+## How to add frontend dependency
+
+1. npm i -D ...
+
+## How to add Sphinx extension to sample docs
+
+1. Add extension to `dependencies` list in `sample_docs/pyproject.toml`.
+1. Add extension to `extensions` list in `conf.py`.

docs/source/features.md

@@ -7,4 +7,7 @@
 :maxdepth: 2
 
 quickstart
+features
+usage
+reference
 ```

docs/source/index.md

@@ -0,0 +1,39 @@
+# Reference
+
+## File layout structure
+
+{{ project }} follows a fairly specific file system layout. This standardized structure eases maintenance and switching between multiple projects.
+
+All tasks, like build and preview, are in the [noxfile.py file](#nox-tasks), and this documentation assumes the structure.
+
+```
+.
+├── build/                  ┐
+│   └── <builder>/          | Output files
+│       └── <language>/     |
+│           └── ...         ┘
+├── source/                 ┐
+│   ├── _static/            |
+│   │   ├── favicon.svg     |
+│   │   └── logo.svg        |
+│   ├── _templates/         | Sphinx project sources
+│   ├── conf.py             | (documents, images, conf.py)
+│   ├── index.md            |
+│   ├── overview.md         |
+│   └── ...                 ┘
+├── .gitignore              ┐
+├── CHANGELOG.md            |
+├── LICENSE                 |
+├── noxfile.py              | Meta files
+├── package-lock.json       |
+├── package.json            |
+└── pyproject.toml          ┘
+```
+
+The files and folders are for three purposes:
+
+- Sphinx project sources. Regular files found in Sphinx projects like .md, .rst, images, conf.py.
+- When built by [tasks](#nox-tasks), output goes to (by default) to `build/`.
+- Meta files. Not the documentation itself. Like dependencies in `pyproject.toml`, license, standard `.gitignore`, etc.
+
+Everything except the output directory should be versioned.

docs/source/reference.md

@@ -4,11 +4,11 @@ orphan: true
 
 # Usage
 
-## Add frontend dependency
+{#nox-tasks}
 
-npm i -D ...
+## noxfile tasks
 
-## Update sample docs
+### preview
 
 In preview mode, Python (Sphinx) and Node.js (Tailwind) part runs in parallel. To distinct the terminal output, both are prefixed with their names.
 
@@ -28,8 +28,8 @@ The `package.json` must contain the following `scripts` tasks. They are called b
   "scripts": {
     "theme:build": "...",
     "theme:watch": "..."
-  }
-}
+  },
+  ...
 ```
 
 For example, if you want to build just Node.js assets, call `npm run theme:build`.