diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index dff5c47b..163adae8 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,7 +11,11 @@ on: - '.github/workflows/docs.yml' - '.github/workflows/deploy.yml' - 'versioning/**' - - 'versioned/**' + - 'AGENTS.md' + - 'CONTRIBUTING.md' + - 'README.rst' + - 'README.md' + - 'docs/maintainers/**' - 'assets/**' - '_templates/**' - 'main/**' diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index e9f1459d..1cc135f6 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -96,6 +96,29 @@ jobs: qr-code: false token: ${{ steps.preview-token.outputs.token }} + - name: Wait until GitHub Pages serves this exact preview revision + if: github.event.pull_request.head.repo.full_name == github.repository + env: + PREVIEW_ROOT: https://libresign.github.io/site-preview/docs-preview/pr-${{ github.event.pull_request.number }} + run: | + # The deploy action pushes gh-pages, but Pages publishes it + # asynchronously. Byte equality of versions.json proves the + # exact documentation revision has reached the public origin. + for attempt in $(seq 1 108); do + if curl -fsSL --max-time 15 -H 'Cache-Control: no-cache' \ + -o /tmp/libresign-live-versions.json \ + "$PREVIEW_ROOT/versions.json?run=$GITHUB_RUN_ID&attempt=$attempt" && + cmp -s _publish/versions.json /tmp/libresign-live-versions.json; then + echo "GitHub Pages serves the expected documentation revision" + break + fi + if [ "$attempt" -eq 108 ]; then + echo "::error::GitHub Pages did not publish this preview revision" >&2 + exit 1 + fi + sleep 10 + done + - name: Check every navigable preview route on the public origin if: github.event.pull_request.head.repo.full_name == github.repository env: @@ -121,7 +144,7 @@ jobs: fi url="$PREVIEW_ROOT$route" success=false - for attempt in $(seq 1 24); do + for attempt in $(seq 1 4); do if curl -fsSL --max-time 15 -H 'Cache-Control: no-cache' \ -o /tmp/libresign-preview-page.html \ "$url?run=$GITHUB_RUN_ID&attempt=$attempt" && diff --git a/AGENTS.md b/AGENTS.md index 05eb7664..e6d5cd4b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,17 +42,18 @@ configuration instruction, rendered example, or troubleshooting step: Check nested required request fields, types/enums, responses, authentication, feature availability, signing state and error cases. OpenAPI shape alone does not prove runtime behavior; the presence of a test is not proof it ran. -3. **Choose the source scope deliberately.** `developer_manual/` is the - development line. `versioned/base/` is for behavior verified in **every** - published stable line; `versioned//` overrides it when any stable - behavior differs. The `main/` directory contains site navigation, not the - development developer manual. Never copy development-only claims into the - stable base, or assume newer features were backported. For an unverified - release, omit or explicitly qualify the claim rather than invent support. +3. **Choose the release branch deliberately.** The `main` branch is + development; `stableNN` contains the complete documentation for LibreSign + major NN. Do not mix Nextcloud major numbers with LibreSign major numbers. + Changes to multiple versions require explicit backports and verification + against the corresponding application contract. 4. **Verify executable examples per release.** Use the correct version-specific fixtures and checks; never make older guides silently use a newer payload. - Add regression coverage for incompatibilities, including negative cases. - Do not weaken a contract check just to keep inherited prose passing. + For ordinary RST pages, do not add Python tests that enumerate page paths, + assert editorial wording or mirror the documentation tree. The existing + Sphinx, link, OpenAPI and multiversion build checks validate those changes. + Add focused regression coverage only when executable contracts or the + documentation tooling itself change. Do not weaken existing contract checks. 5. **Review versioned links and surrounding pages.** Avoid silently linking older manuals to `/main/`, `/latest/`, or moving source-branch URLs when claiming version-specific support. Inspect related pages across all three @@ -65,14 +66,13 @@ configuration instruction, rendered example, or troubleshooting step: scenarios, and behaviors are verified versus untested. Green Sphinx/CI checks are not proof of real signing, SMTP, policies, or file permissions. -This repository builds stable versions from `versioned/base/` plus overlays, -not from separate documentation branches as Nextcloud does. Directory scopes -shared from the development manual into stable builds are declared in -`versioned/shared.json`, never hardcoded per page in build scripts. Preserve the -existing dynamic discovery and build infrastructure. For authoring details -and the external-email-signers fixture conventions, read -[CONTRIBUTING.md](CONTRIBUTING.md). Application behavior and API contract -changes belong in `LibreSign/libresign` and require a separate change there. +Each release branch contains complete `main/`, `user_manual/`, `admin_manual/` +and `developer_manual/` source directories. There is no `versioned/base` or +per-file overlay mechanism. The central publishing tool checks out the exact +documentation branch and pins the application OpenAPI separately. A missing +stable documentation branch must fail rather than inherit development prose. +For authoring instructions read [CONTRIBUTING.md](CONTRIBUTING.md). +Application source and API changes belong to `LibreSign/libresign`. ## Quality gates diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 80155077..ea28304c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,117 +1,72 @@ - + # Contributing to LibreSign documentation -This repository contains LibreSign's public user, administrator, and developer -documentation. Choose the manual for your reader: `user_manual/`, -`admin_manual/`, or `developer_manual/`. The `main/` directory provides -top-level navigation. Follow the existing manual structure and write about the -product or procedure, not the history of implementing a change. Explain concepts -before advanced details, link to existing explanations instead of duplicating -them, verify internal links and cross-references, and use examples without real -personal or customer data. +You can edit the documentation without knowing Python or the site generator. -## Build and review your change +## Select a version -From the repository root, install Python 3.13 and the dependencies from the root -`requirements.txt` in a virtual environment. For example: +The branch **is** the LibreSign documentation version: + +| Branch | Documentation | +| --- | --- | +| `main` | Next LibreSign release (development) | +| `stable15` | LibreSign 15 | +| `stable14` | LibreSign 14 | +| `stable13` | LibreSign 13 | + +New releases follow `stableNN`, where `NN` is the **LibreSign** major, not +Nextcloud's major. The published version selector and **Edit on GitHub** links +should take you to the matching branch automatically. + +## Edit one page + +1. Open the version and manual you want to change at https://docs.libresign.coop. +2. Select **Edit on GitHub** or browse the corresponding branch. +3. Edit the RST file under `user_manual/`, `admin_manual/` or `developer_manual/`. +4. For a new page, add its name to the section `index.rst` (`.. toctree::`). +5. Create a pull request targeting the **same** branch. +6. Review the HTML preview and fix any Sphinx warnings or broken links. + +**No Python test, manual file manifest, or generator change is needed to add a +page.** The CI builds the manual and checks internal links automatically. + +## Make a fix available in multiple versions + +Correct the newest applicable version first. Backport the same change to each +older `stableNN` branch that needs it (one PR per target branch). Do not assume +that an API operation or configuration option is available in an older release. + +API examples must match the pinned application OpenAPI and implementation for +the intended LibreSign version. The documentation builds use the application +manifest and the exact application commit; a Nextcloud version or an OCS +`/api/v1` URL does not establish feature compatibility. + +## Preview locally + +Install Python and the dependencies in a virtual environment, then run: ```sh -python -m venv .venv -# Activate .venv for your shell, then: python -m pip install -r requirements.txt +sphinx-build -n -W developer_manual _build/developer_manual ``` -Build every manual whose rendered pages you changed before opening a pull -request. The root `Makefile` provides `make main`, `make user`, `make admin`, -`make dev`, and `make all`. If `make` is unavailable, use the same Sphinx commands -as the [Documentation CI workflow](.github/workflows/docs.yml): +Replace `developer_manual` with the manual you changed. The PR workflow also +validates all published releases, API provenance, SEO and links. -```sh -sphinx-build main _build/main -sphinx-build user_manual _build/user_manual -sphinx-build admin_manual _build/admin_manual -sphinx-build -W developer_manual _build/developer_manual -``` +Do not rename published pages without preserving their URLs with redirects. +Never put credentials or real customer data into examples. + +## New stable LibreSign release + +The maintainers create `stableNN` from the approved development (`main`) manual +when the LibreSign application releases that major. Public versions are +discovered from the application manifest, not a hardcoded list in the site. +The branch must exist before the documentation build can publish that release. + +## Commit policy -Run the affected command(s), not necessarily all four; CI builds every -version. For stable or cross-version edits, run -`python -m versioning.build --output _build` when network access is available; -it uses pinned application contracts. The developer manual is built with -warnings treated as errors. The PR workflow publishes a navigable preview -for visual checking of headings, code blocks, links and layout. No -screenshot attachment or Python change is required to add an RST page. - -## Version-scoped integration documentation - -The published version selector does not by itself make prose compatible with -an older LibreSign release. The build discovers application releases from -`appinfo/info.xml`, pins each source commit and publishes that commit's -`openapi.json`. The exact LibreSign/Nextcloud versions are available in -Sphinx as `|LibreSignRelease|` and `|NextcloudRelease|`. - -The source layout deliberately has three different scopes: - -- `developer_manual/` describes the development (`main`) application. -- `versioned/base/` contains only claims verified across the published - stable releases. Do not copy development-only behavior into this base. -- `versioned//` overrides stable content when a release differs. -- `versioned/shared.json` lists **directory scopes**, not individual pages, - that are already verified as release-safe and can be copied from the - development manual into stable builds. New RST files inside a declared - section are included automatically. Add a new directory to this small - declarative file only when all relevant stable releases support its content. - Keep development-only pages outside shared scopes. - -Use `.. toctree::` in your RST section index so Sphinx can discover the -new page. No Python file needs modification to add a page, section or -version-specific override; keep release discovery dynamic. - -For the external-email-signers guide, each supported application line has -a reviewed `examples/external-email-signers/request-.json` and a -`_external-email-signers-release.inc` in its own source directory. -The Sphinx include extension `.inc` prevents these snippets from being -treated as additional standalone manual pages. The CLI clients refuse -to choose a fixture implicitly: `LIBRESIGN_DOC_LINE` selects a reviewed -release explicitly. When a new release is discovered, add its reviewed -fixture and overlay rather than inheriting an older identity schema. - -The Documentation CI gate validates the actual nested request fields -and example JSON against **that version's pinned OpenAPI**, checks -guarded controller and Playwright source files from the **same pinned -application commit**, and rejects unknown/new releases without reviewed -examples. It does not assert that browser signing, SMTP or certificate -verification passed in a live environment. Record those executions -separately when performed. Changes to an API contract must be made in -the LibreSign application repository and regenerated there; do not -modify the pinned JSON inside the documentation repository. - -## Pull request preview and evidence - -Link the relevant issue and describe the affected versions. The workflow -publishes the complete multiversion HTML preview on an isolated origin and -checks its public URLs. Review the rendered result by opening its links: -navigation, responsive layout, dark mode, code blocks and cross-references -are easier to verify there than in static screenshots. No screenshots are -required, and you do not need to edit Python for ordinary RST contributions. - -Documentation for an unreleased application major is rendered into a separate -`/_review/` preview area, with direct links in a PR comment. It does not -appear in production Pages or the published version selector. Future-release -content uses development application metadata for preview, not an invented -stable OpenAPI. Contributor fork previews use the same isolated static HTML -site, deployed by a privileged workflow that does not execute fork code. - -Keep each pull request focused. Report the tests actually run and any known -runtime coverage gaps; never include secrets, private documents or real -customer data in examples or previews. - -## Developer Certificate of Origin - -Sign off each commit to certify the [Developer Certificate of Origin](https://developercertificate.org/). -With your Git name and email configured, use `git commit -s -m "Your message"`. -The resulting `Signed-off-by: Name ` trailer must identify you; use an -email associated with your GitHub account if you want GitHub to attribute it. +Sign off every commit according to the +[Developer Certificate of Origin](https://developercertificate.org/). +A GitHub verified signature is also required when enforced by the repository. diff --git a/README.md b/README.md index 2f054799..fe602065 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,33 @@ - + # LibreSign documentation -Source for the [LibreSign public documentation](https://docs.libresign.coop/), -built with Sphinx. The site provides separate manuals for stable LibreSign -majors (`/13/`, `/14/`, `/15/`) and development (`/main/`). - -- **Edit content:** use RST in `developer_manual/`, `user_manual/` or - `admin_manual/`. The `versioned/base/` directory holds stable foundations; - `versioned//` holds overrides. Shared development-to-stable sections - are listed in `versioned/shared.json`. Adding a page never requires editing - Python build or screenshot scripts. -- **Contribute:** open a PR. CI checks Sphinx, links, OpenAPI provenance and - version isolation. Review the navigable preview, including any unpublished - release pages under `/_review/`; screenshots are not required. -- **Maintain releases:** see the - [maintainer guide](docs/maintainers/versioning.md) for local builds, - deployment, previews, backports and lifecycle metadata. - -Canonical release history and API sources remain in -[LibreSign/libresign](https://github.com/LibreSign/libresign). +Public manuals: **https://docs.libresign.coop**. + +The documentation follows Nextcloud's **one branch per version** pattern: + +| Branch | LibreSign documentation | +| --- | --- | +| `main` | Next release, in development | +| `stable15` | LibreSign 15 | +| `stable14` | LibreSign 14 | +| `stable13` | LibreSign 13 | + +For a new release, use `stableNN`, where NN is the **LibreSign major** (not the +Nextcloud server major). Each branch contains complete `user_manual/`, +`admin_manual/` and `developer_manual/` sources. There are no `versioned/` +source overlays and no per-page Python tests to update. + +**To edit a page:** choose the LibreSign version on the website, select +**Edit on GitHub**, update the RST file and open a PR to the **same branch**. +For a new page, add it to the section's `index.rst` (`.. toctree::`). +For changes applying to multiple versions, backport explicitly. + +See [CONTRIBUTING.md](CONTRIBUTING.md) for everyday editing and +[docs/maintainers/versioning.md](docs/maintainers/versioning.md) for the +publication process, API contracts and new releases. + +The build dynamically discovers released LibreSign majors and pins their +OpenAPI contracts to their exact application commits. Releases are never +inferred from a documentation branch alone. diff --git a/README.rst b/README.rst index fe6622ff..23da1590 100644 --- a/README.rst +++ b/README.rst @@ -2,156 +2,11 @@ LibreSign Documentation ======================= -Documentation is published on ``_. -To edit it yourself, you need to tinker a bit with Git and Sphinx. -See the `Style Guide `_ for formatting and style conventions. +Public manuals are available at https://docs.libresign.coop. -Manuals -------- +See `README.md `_ for the +version-to-branch mapping and `CONTRIBUTING.md +`_ +for the editing guide. -This repository hosts three manuals: - -* **Users' Manual** -* **Administration Manual** -* **Developers Manual** - -Please wrap lines at 80 characters. - -Spelling and Capitalization Conventions ---------------------------------------- - -* Nextcloud -* LibreSign - -License -------- - -All documentation in this repository is licensed under the Creative Commons -Attribution 3.0 Unported license (`CC BY 3.0`_). - -.. _CC BY 3.0: https://creativecommons.org/licenses/by/3.0/deed.en_US - -Style ------ - -Source files are written using the `Sphinx Documentation Generator -`_. The syntax follows the `reStructuredText -`_ style, and can also be edited -from GitHub. - -Structure ---------- - -Of course, think about structure. Keep in mind that we try NOT to move or rename -pages once they are created! Lots of external sources link to our documentation, -including the indexing by search engines of course. So once you create a page with a certain -name, it has to stay in that location and with that name. Think of it as API stability -- we have to ensure things stay as they are as much as possible. Renaming or moving -is only allowed in exceptional circumstances and only when a redirect is put in place. - -Editing -------- - -Contributing to the documentation requires a GitHub account. - -To edit a document, you can edit the .rst files on your local system, or work -directly on GitHub. The latter is only suitable for small fixes and improvements -because substantial editing efforts can better be controlled on your local PC. - -The best way is to install a complete Sphinx build environment and work on your -local PC or using the docker-compose that stay at home folder of this repository. -You will be able to make your own local builds, which is the fastest -and best way to preview for errors. Sphinx will report syntax errors, missing -images, and formatting errors. The GitHub preview is not complete and misses -many mistakes. Create a new branch against the main, make your edits, then push -your new branch to GitHub and open a new PR. - -To edit on GitHub, fork the repository (see top-right of the screen, under -your username). You will then be able to make changes easily. Once done, -you can create a pull request and get the changes reviewed and back into -the official repository. - -When editing either on your own local PC or on GitHub, be sure to sign of -commits, to certify adherence to the Developer Certificate of Origin, -see https://github.com/probot/dco . Your commit messages need to have, -the name and email address of the contributor. - - Signed-off-by: Awesome Contributor - -If using the command line and your name and email are configured, you can use - - git commit -s -m 'Commit message' - -In both settings be sure that your email address matches that in your GitHub profile, -which if you have privacy enabled will be github.username@users.noreply.github.com - - -Building --------- - -Building HTML -============= - -Using pipenv -^^^^^^^^^^^^ - -1. Install ``pipenv`` - https://pipenv.readthedocs.io/en/latest/ -2. Change into the environment: ``pipenv shell`` -3. Install the dependencies ``pip install -r docs/requirements.txt`` -4. Now you can use ``make ...`` to build all the stuff - for example ``make html`` to build the HTML flavor of all manuals - The build assets will be put into the individual documentation subdirectories like ``developer_manual/_build/html/com`` - -To change into this environment you need to run ``pipenv shell`` to launch the shell and to exit you can use either ``exit`` or ``Ctrl`` + ``D``. - -Using venv -^^^^^^^^^^ - -1. Install ``python3-venv`` -2. Only once: Create a venv (typically inside this repository): ``python -m venv venv`` -3. Activate the environment (inside this repository): ``source venv/bin/activate`` -4. Install the dependencies ``pip install -r docs/requirements.txt`` -5. Now you can use ``make ...`` to build all the stuff - for example ``make html`` to build the HTML flavor of all manuals - The build assets will be put into the individual documentation subdirectories like ``developer_manual/_build/html/com`` - -Autobuilding -^^^^^^^^^^^^ - -When editing the documentation installing ``sphinx-autobuild`` though pip can be helpful. This will watch file changes and automatically reload the html preview: - -1. Install ``pip install sphinx-autobuild`` -2. Enter the documentation section ``cd user_manual`` -3. Watch for file changes ``make SPHINXBUILD=sphinx-autobuild html`` -4. Open http://127.0.0.1:8000 in the browser and start editing - -Using the VSCode DevContainer -============================= - -This repository contains a full-featured `VSCode DevContainer `_. -You can use it in your local development environment or via `GitHub Codespaces `_. -Just open the container an use one of the commands from above to build the project. For example ``make`` to build the full -documentation. You can also use ``make SPHINXBUILD=sphinx-autobuild html`` -in combination with `port forwarding `_ -to watch file changes and automatically reload the html preview. - -Usign docker -============ -You can also use the `docker-compose.yml` file to build the documentation using -Docker. This is useful if you want to avoid installing Python and its -dependencies on your local machine. - -1. Make sure you have Docker and Docker Compose installed. -2. Open a terminal and navigate to the root directory of the repository. -3. Run the following command to build the documentation: - - ``docker-compose up`` - - This will build the HTML documentation and place it in the `volumes/html` directory. - And also will start a HTTP server and you can access the documentation at `http://localhost:8000`. - -4. To stop the server, press `Ctrl+C` in the terminal. - - -.. _CC BY 3.0: https://creativecommons.org/licenses/by/3.0/deed.en_US -.. _`Xcode command line tools`: https://stackoverflow.com/questions/9329243/xcode-install-command-line-tools - -This README was based on the `Nextcloud documentation `_. \ No newline at end of file +All documentation is licensed under Creative Commons Attribution 3.0 Unported. diff --git a/_templates/home.html b/_templates/home.html index afa3fcb4..453e0e9d 100644 --- a/_templates/home.html +++ b/_templates/home.html @@ -58,7 +58,7 @@

Available versions

- {% if entry.slug == 'main' %}main{% else %}LibreSign {{ entry.slug }}{% endif %} + {% if entry.slug == 'main' %}{% if entry.app_version is defined %}LibreSign {{ entry.app_version.split('.')[0] }}{% else %}Development{% endif %}{% else %}LibreSign {{ entry.slug }}{% endif %}

{% if entry.status == 'development' %}Development (not a stable release) @@ -68,7 +68,7 @@

Nextcloud {{ entry.nextcloud_min }}{% if entry.nextcloud_min != entry.nextcloud_max %}–{{ entry.nextcloud_max }}{% endif %}

-