Writing this documentation
This site is built with Kiln from two sources:
- The guides: the Markdown files of
docs/, configured bydocs.ymlat the repository root (title, logo, accent color, sidebar). - The API reference: rendered by Kiln under
/api/fromapi.json, a description of thesokpackage that griffe writes from the source code and its docstrings.docs.ymllists the modules left out (api.exclude): the interface,sok.ui, is not part of it.
site/ and api.json are generated and ignored by git.
Preview
Section titled “Preview”Kiln runs in Docker, so the only requirement besides uv is Docker:
uv run --extra docs python scripts/build_docs.py serveThe site opens on http://localhost:4321 and reloads when a page changes. After
changing docstrings, run build_docs.py api in another terminal: the reference
pages reload with the new api.json.
| Command | Effect |
|---|---|
build_docs.py or build_docs.py build |
Writes api.json, then builds the site into site/ |
build_docs.py serve |
Writes api.json, then previews the site |
build_docs.py api |
Only writes api.json |
build_docs.py clean |
Removes site/ and api.json |
Write a page
Section titled “Write a page”Each page is a Markdown file with a front matter:
---title: Page titledescription: One sentence, shown under the title and in search results.---
Content in Markdown.Add the page to the sidebar list of docs.yml, without the extension:
guides/example. Links between pages are absolute and end with a slash:
[Building](/guides/building/).
Callouts use this syntax: :::note, :::tip, :::caution and :::danger,
closed by :::. Kiln’s own documentation lists the other components.
Write for someone who knows Python but not S.O.K. Check every command and code example against the code before publishing it.
Publishing
Section titled “Publishing”.github/workflows/docs.yml publishes the site to GitHub Pages each time main
moves, that is at each release: the online documentation always matches the
released app. It calls Kiln’s reusable workflow, which writes api.json with
griffe, builds the site and deploys it. It can also be run by hand from the
Actions tab.
The workflow builds what git tracks, so a file left untracked in docs/ never
reaches the published site.
Docstrings
Section titled “Docstrings”The API reference reads Google-style docstrings:
async def search(self, query: str, content_type: ContentType, **kwargs: Any) -> Dict[str, Any]: """Search the service.
Args: query: Text typed by the user. content_type: What to search for. **kwargs: Service-specific options, such as "language" or "year".
Returns: A dictionary whose "results" key holds the matches.
Raises: APIConnectionError: If the service cannot be reached. """It covers sok.core, sok.apis, sok.media, sok.file_operations and
sok.config. The interface (sok.ui) is left out.