From cd1c4057cac2e0d962ca1cb6c843f954d09897dd Mon Sep 17 00:00:00 2001 From: Louis Maddox Date: Sun, 14 Jan 2024 12:50:51 +0000 Subject: [PATCH 1/4] test: add a docstring that will be used to test the new autorefs syntax works --- src/foo/src/foo/main.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/foo/src/foo/main.py b/src/foo/src/foo/main.py index bf13b11..7851c9b 100644 --- a/src/foo/src/foo/main.py +++ b/src/foo/src/foo/main.py @@ -8,6 +8,8 @@ class A(BaseModel): """ This is an example of a documented Pydantic model. + [foo.main.A.x][] should give the same link as [.x][foo.main.A.x] + Attributes: x: An example number. y: An example string. From a14caac7c2b91a305a7f5ef779bf3385a0b45f50 Mon Sep 17 00:00:00 2001 From: Louis Maddox Date: Sun, 14 Jan 2024 15:20:42 +0000 Subject: [PATCH 2/4] docs: delete unnecessary extra parts (easier to inspect debug output with fewer docstrings processed) --- README.md | 123 --------------------------- docs/api/bar.md | 1 - docs/usage/bar.md | 1 - docs/usage/foo.md | 1 - docs/usage/index.md | 18 ---- mkdocs.yml | 5 -- src/bar/.gitignore | 162 ------------------------------------ src/bar/README.md | 7 -- src/bar/pyproject.toml | 18 ---- src/bar/src/bar/__init__.py | 0 src/bar/src/bar/main.py | 9 -- src/bar/tests/__init__.py | 0 12 files changed, 345 deletions(-) delete mode 100644 docs/api/bar.md delete mode 120000 docs/usage/bar.md delete mode 120000 docs/usage/foo.md delete mode 100644 docs/usage/index.md delete mode 100644 src/bar/.gitignore delete mode 100644 src/bar/README.md delete mode 100644 src/bar/pyproject.toml delete mode 100644 src/bar/src/bar/__init__.py delete mode 100644 src/bar/src/bar/main.py delete mode 100644 src/bar/tests/__init__.py diff --git a/README.md b/README.md index 02fa467..c2603e5 100644 --- a/README.md +++ b/README.md @@ -1,124 +1 @@ # docs-pkg - -A suite of documented packages built with [mkdocs.org](https://www.mkdocs.org). - -## Commands - -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs -h` - Print help message and exit. - -## Project layout - -The layout is straightforward but notice the symlinks that let the documentation live alongside associated code. - -This repo mimics the layout of a monorepo containing two example Python packages. Note that they -don't need to ever be installed to build the docs, so the top-level `pyproject.toml` just stores -a `docs` dependency group. - -``` -. -├── docs -│   ├── api -│   │   ├── bar.md -│   │   ├── foo.md -│   │   └── index.md -│   ├── index.md -> ../README.md # The documentation homepage. -│   ├── stylesheets -│   │   └── extra.css -│   ├── theme -│   └── usage -│   ├── bar.md -> ../../src/bar/README.md -│   ├── foo.md -> ../../src/foo/README.md -│   └── index.md -├── LICENSE.txt -├── mkdocs.yml # The configuration file. -├── pdm.lock -├── pyproject.toml -├── README.md -└── src -    ├── bar -    │   ├── pyproject.toml -    │   ├── README.md -    │   ├── src -    │   │   └── bar -    │   └── tests -    └── foo -    ├── pyproject.toml -    ├── README.md -    ├── src -    │   └── foo -    └── tests -``` - -## Tips on documenting your code - -- If the `show_if_no_docstring` flag is on (default: off) you must put a docstring in a class or it won't get documented - -- You can override all of the settings in an `options` block per-file beneath an autodoc instruction (`:::` followed by a - dotted path to the module/object) - - - One important setting to override is `members` which lets you list the members in the order you want them to appear. - - Otherwise, they appear in alphabetical order (the `members_order` setting defaults to - `"rendering.Order.alphabetical.value"`, I prefer changing it to `"source"`). - -## Deploying with Vercel - -### Configuring Vercel to build a `mkdocs` website - -The Vercel deployment config is stored in `vercel.json` at the project root. - -It equates to setting the following manually in the web view -(but it's easier to let it be configured automatically from the JSON file): - -- **Build command** `mkdocs build` -- **Output directory** `site` -- **Install command** is the command below, but all on one line: - -```bash -python3 --version && \ -python3 -m pip install -v -r docs/reqs/vercel.txt && \ -python3 -m mkdocs -``` - -The pre-commit hook in [`.pre-commit-config.yaml`][pchook] freezes the dependency lockfile into a static list -of requirements at [`docs/reqs/vercel.txt`][vercelreqs]. There's a `vercel` development dependency group in the -[`pyproject.toml`][verceldg] config pinning `urllib3<2` without which mkdocs will fail. - -[pchook]: https://github.com/lmmx/docs-pkg/blob/1ecde3785a79a5ef0a57ef54f27925ed95074434/.pre-commit-config.yaml#L47-L53 -[vercelreqs]: https://github.com/lmmx/docs-pkg/blob/master/docs/reqs/vercel.txt -[verceldg]: https://github.com/lmmx/docs-pkg/blob/1ecde3785a79a5ef0a57ef54f27925ed95074434/pyproject.toml#L36-L38 - -> The `urllib3` is pinned like this because Vercel "runners" are based on the -> Amazon Linux 2 container image (a variant of RHEL, which has OpenSSL v1.0.2 -> whereas the `urllib3` v2 release [imposes](https://github.com/urllib3/urllib3/issues/2168) -> a minimum of OpenSSL v1.1.1). - -### Vercel integration with GitHub - -#### Privacy - -The Vercel website checks if you're logged into GitHub when you load it. -If your repo is private, the website will be gated by a GitHub login. -This repo is public ([here](https://github.com/lmmx/docs-pkg)) therefore -so is the website (the default branch deployment [here](https://docs-pkg-git-master-lmmx.vercel.app/) as well as all the other PR/commit-specific deployments). - -#### CI bot - -To install a Vercel CI bot that will comment on all of your PRs, -install the [Vercel GitHub App](https://github.com/apps/vercel) -on your account (configurable for all repos or select repos). - -This gives both PR deployment and a main trunk deployment -(visible from the _Deployments_ panel on the right hand side of the repo front page or at -[`/deployments`](https://github.com/lmmx/docs-pkg/deployments)). - -#### Vercel config documentation - -See these official docs for more details: - -- [**Project configuration**](https://vercel.com/docs/projects/project-configuration): reference - for the Vercel JSON format. -- [**Vercel for GitHub**](https://vercel.com/docs/deployments/git/vercel-for-github): referenc for - the Vercel GitHub app. diff --git a/docs/api/bar.md b/docs/api/bar.md deleted file mode 100644 index 3e992d3..0000000 --- a/docs/api/bar.md +++ /dev/null @@ -1 +0,0 @@ -::: bar diff --git a/docs/usage/bar.md b/docs/usage/bar.md deleted file mode 120000 index 64c2704..0000000 --- a/docs/usage/bar.md +++ /dev/null @@ -1 +0,0 @@ -../../src/bar/README.md \ No newline at end of file diff --git a/docs/usage/foo.md b/docs/usage/foo.md deleted file mode 120000 index 86edc5a..0000000 --- a/docs/usage/foo.md +++ /dev/null @@ -1 +0,0 @@ -../../src/foo/README.md \ No newline at end of file diff --git a/docs/usage/index.md b/docs/usage/index.md deleted file mode 100644 index f0c8111..0000000 --- a/docs/usage/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: User guides ---- - -## About - -The user guides in this section are intended to offer a straightforward overview for users - -:envelope: Don't hesitate to reach out if you have questions or need further clarification. - -## Legend - -| Symbol | Meaning | -| ------------------------------- | ---------------------------------------------- | -| :fontawesome-solid-power-off: | The service is not in use or out of order. | -| :fontawesome-solid-ban: | The service's entire documentation is missing. | -| :fontawesome-solid-toggle-off: | The API interface documentation is missing. | -| :fontawesome-solid-toggle-on: | The API interface documentation is available. | diff --git a/mkdocs.yml b/mkdocs.yml index e5a9a27..ec22a33 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -95,11 +95,6 @@ plugins: nav: - Home: index.md - - Usage: - - User guides: usage/index.md - - usage/bar.md - - usage/foo.md - API Reference: - APIs: api/index.md - - api/bar.md - api/foo.md diff --git a/src/bar/.gitignore b/src/bar/.gitignore deleted file mode 100644 index 3a8816c..0000000 --- a/src/bar/.gitignore +++ /dev/null @@ -1,162 +0,0 @@ -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. -*.manifest -*.spec - -# Installer logs -pip-log.txt -pip-delete-this-directory.txt - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# Translations -*.mo -*.pot - -# Django stuff: -*.log -local_settings.py -db.sqlite3 -db.sqlite3-journal - -# Flask stuff: -instance/ -.webassets-cache - -# Scrapy stuff: -.scrapy - -# Sphinx documentation -docs/_build/ - -# PyBuilder -.pybuilder/ -target/ - -# Jupyter Notebook -.ipynb_checkpoints - -# IPython -profile_default/ -ipython_config.py - -# pyenv -# For a library or package, you might want to ignore these files since the code is -# intended to run in multiple environments; otherwise, check them in: -# .python-version - -# pipenv -# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. -# However, in case of collaboration, if having platform-specific dependencies or dependencies -# having no cross-platform support, pipenv may install dependencies that don't work, or not -# install all needed dependencies. -#Pipfile.lock - -# poetry -# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control -#poetry.lock - -# pdm -# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. -#pdm.lock -# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it -# in version control. -# https://pdm-project.org/#use-with-ide -.pdm.toml -.pdm-python -.pdm-build/ - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Celery stuff -celerybeat-schedule -celerybeat.pid - -# SageMath parsed files -*.sage.py - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Spyder project settings -.spyderproject -.spyproject - -# Rope project settings -.ropeproject - -# mkdocs documentation -/site - -# mypy -.mypy_cache/ -.dmypy.json -dmypy.json - -# Pyre type checker -.pyre/ - -# pytype static type analyzer -.pytype/ - -# Cython debug symbols -cython_debug/ - -# PyCharm -# JetBrains specific template is maintained in a separate JetBrains.gitignore that can -# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore -# and can be added to the global gitignore or merged into this file. For a more nuclear -# option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ diff --git a/src/bar/README.md b/src/bar/README.md deleted file mode 100644 index b0af9aa..0000000 --- a/src/bar/README.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -icon: fontawesome/solid/toggle-off ---- - -# Bar - -This is an example of a service which does very little for now. diff --git a/src/bar/pyproject.toml b/src/bar/pyproject.toml deleted file mode 100644 index 3cea965..0000000 --- a/src/bar/pyproject.toml +++ /dev/null @@ -1,18 +0,0 @@ -[build-system] -build-backend = "pdm.backend" -requires = ["pdm-backend"] - -[project] -authors = [ - {email = "louismmx@gmail.com", name = "Louis Maddox"}, -] -dependencies = [] -description = "bar" -license = {text = "MIT"} -name = "bar" -readme = "README.md" -requires-python = ">=3.11" -version = "0.1.0" - -[tool.pdm] -package-type = "library" diff --git a/src/bar/src/bar/__init__.py b/src/bar/src/bar/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/src/bar/src/bar/main.py b/src/bar/src/bar/main.py deleted file mode 100644 index 8dedb36..0000000 --- a/src/bar/src/bar/main.py +++ /dev/null @@ -1,9 +0,0 @@ -__all__ = ["example_function"] - - -def example_function(a: int, b: str = "hello this is bar:main.b") -> None: - """ - This is the example function provided by the bar package. - """ - print(a, b) - return diff --git a/src/bar/tests/__init__.py b/src/bar/tests/__init__.py deleted file mode 100644 index e69de29..0000000 From 26ddfd2131b07cbd073376724819e5725085115b Mon Sep 17 00:00:00 2001 From: Louis Maddox Date: Sun, 14 Jan 2024 15:26:43 +0000 Subject: [PATCH 3/4] docs: reduce to 1 link --- src/foo/src/foo/main.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/foo/src/foo/main.py b/src/foo/src/foo/main.py index 7851c9b..d8af36d 100644 --- a/src/foo/src/foo/main.py +++ b/src/foo/src/foo/main.py @@ -8,7 +8,7 @@ class A(BaseModel): """ This is an example of a documented Pydantic model. - [foo.main.A.x][] should give the same link as [.x][foo.main.A.x] + [.x][foo.main.A.x] Attributes: x: An example number. From 41945fd5b8e35576f760532bfe665e18d988b223 Mon Sep 17 00:00:00 2001 From: Louis Maddox Date: Sun, 14 Jan 2024 19:21:08 +0000 Subject: [PATCH 4/4] feat: use a relative reference (thus break docs deployment build) --- src/foo/src/foo/main.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/foo/src/foo/main.py b/src/foo/src/foo/main.py index d8af36d..102e544 100644 --- a/src/foo/src/foo/main.py +++ b/src/foo/src/foo/main.py @@ -1,14 +1,15 @@ -from pydantic import BaseModel +from dataclasses import dataclass __all__ = ["A"] -class A(BaseModel): +@dataclass +class A: """ - This is an example of a documented Pydantic model. + This is an example of a documented class. - [.x][foo.main.A.x] + [.x][] Attributes: x: An example number.