Every library here follows these rules, and a new one must too: the site checks them at each library's latest release and does not build while one is broken. A library joins the site when it follows them and is added to site.toml with its group. How the site reads and shows the libraries: /doc/site.md, the README of the site's repository.
-
project() declares the library: its name, a VERSION X.Y.Z (or a VERSION file holding
it, which project() reads), a DESCRIPTION, which is the library's line on the site,
HOMEPAGE_URL "https://offerrall.github.io/<name>/", and LANGUAGES C or LANGUAGES CXX.
project(imagekit VERSION 1.0.0
DESCRIPTION "GPU image processing with WebGPU"
HOMEPAGE_URL "https://offerrall.github.io/imagekit/"
LANGUAGES CXX)
-
One target, installed for find_package: add_library(<name> ...), exported with
install(EXPORT ... NAMESPACE <name>::), so a user writes find_package(<name>) and links
<name>::<name>.
-
The language standard is declared: target_compile_features(<name> PUBLIC cxx_std_NN)
(c_std_NN in C), or CMAKE_CXX_STANDARD / CMAKE_C_STANDARD.
-
The license is one the site recognizes by its text: MIT, Apache-2.0, BSD-3-Clause,
BSD-2-Clause, GPL-3.0, LGPL-3.0, MPL-2.0 or Zlib.
-
The README declares the dependencies in a ## Dependencies section after
## Documentation, since CMake has no one place that declares them. One line per
dependency: its name, its version in pip's notation (==, >=, <, , between clauses),
and marks in parentheses: bundled when CMake downloads and builds it, optional: <option>
when only that CMake option needs it. Without marks it comes from the system. None. when
there are none. Another of these libraries is pinned exactly, as in Python.
## Dependencies
- zstd `==1.5.6` (bundled)
- lcms2 `>=2.16`
- harfbuzz `>=2.6` (optional: IMAGEKIT_BUILD_TEXT)
-
README.md is a short entrance: the library's name as title, without a version (the name of
the repository is accepted too), a presentation of at most 40 lines with at most one block of
code, the line The full documentation is at https://offerrall.github.io/<name>/., and a
## Documentation section, its only section (a C or C++ library adds ## Dependencies after it).
-
The ## Documentation list is the site's menu, and it links the site: every page under
docs/, subfolders included, one per line, in reading order, each linked by its address on the
site, so a reader on GitHub or PyPI lands there. docs/<page>.md is
https://offerrall.github.io/<name>/<page>/, and docs/overview.md is the library's own
address, listed first. An entry may be followed by a one-line description. The list links nothing
else (the site adds the changelog), and has no subheadings.
## Documentation
- [Overview](https://offerrall.github.io/pytypehint/): what it is and how it works.
- [Getting started](https://offerrall.github.io/pytypehint/getting-started/): a first example.
-
docs/overview.md is the introduction: on the site, the Overview page is the README's
presentation followed by it.
-
Every page under docs/ is in the list, every entry of the list exists, and no page is
named docs/index.md. All the documentation lives in README.md and docs/: no other README
anywhere in the repository.
-
A page starts with its one title (# Title), and its entry in the list uses that same title.
-
Notes for maintainers close the page they explain, folded, never as pages of their own:
<details>
<summary>How it works inside</summary>
Why the upload endpoint does not apply the size bounds of a field...
</details>
-
Every block of code names its language (```python, ```bash, ```text...).
-
No badges (img.shields.io): the site shows version, language and license itself.
-
Every relative link works: to a file of the repository, and to a heading (#anchor) of a
page. Links are written as they work on GitHub, and no page links to README.md. The site
publishes the images in docs/images/; any other file is linked on GitHub.
-
Another of these libraries is linked by its page on the site, not by its GitHub repository.
-
CHANGELOG.md headings are ## X.Y.Z - YYYY-MM-DD, newest first, with real dates.