Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions .github/workflows/manual-editions.yml
Original file line number Diff line number Diff line change
Expand Up @@ -85,3 +85,46 @@ jobs:
manual-artifacts/
if-no-files-found: warn
retention-days: 14
publish:
# The build job runs third-party tooling with a read-only token. Only this
# job, which runs no repository code, can write the release assets.
name: Publish development manual editions
needs: editions
if: github.ref == 'refs/heads/develop' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
runs-on: ubuntu-24.04
timeout-minutes: 10
permissions:
contents: write
concurrency:
group: manual-editions-publish
cancel-in-progress: false
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
RELEASE_TAG: manuals-develop
steps:
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333
with:
name: cacti-manual-editions-attempt-${{ github.run_attempt }}
path: built
- name: Stage release assets under stable names
run: |
set -euo pipefail
mkdir assets
cp built/resource/pdf/cacti-manual.pdf assets/
cp built/resource/pdf/build_manifest.json assets/cacti-manual-manifest.json
cp built/resource/manuals/build-manifest.json assets/editions-manifest.json
for file in built/resource/manuals/*.pdf built/resource/manuals/*.txt built/resource/manuals/*.sql; do
cp "$file" assets/
done
test "$(find assets -type f | wc -l)" -eq 21
- name: Replace the development release assets
run: |
set -euo pipefail
notes="Development (Cacti 1.3) manual editions built and verified from ${GITHUB_SHA::12}. Rebuilt after each change to develop."
if ! gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
gh release create "$RELEASE_TAG" --target "$GITHUB_SHA" --prerelease --latest=false \
--title 'Development manual editions' --notes "$notes"
fi
gh release upload "$RELEASE_TAG" assets/* --clobber
gh release edit "$RELEASE_TAG" --notes "$notes"
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,7 @@ html-artifacts/
/manual-artifacts/
navigation-report.json
!.gitattributes
# Generated manual editions are published as release assets
/resource/manuals/
/resource/pdf/cacti-manual.pdf
/resource/pdf/build_manifest.json
2 changes: 1 addition & 1 deletion Development-and-Testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Check Markdown style, spelling, navigation targets, image paths, and heading
fragments. Preserve public page names and existing fragment links when
reorganizing a page. Generated manuals must follow the same chapter order and
record their source revision and checksums in the
[download manifest](resource/pdf/build_manifest.json).
[download manifest](https://github.com/Cacti/documentation/releases/download/manuals-develop/cacti-manual-manifest.json).

[standards]: Manual-Index.md#development-standards
[contributing]: https://github.com/Cacti/cacti/blob/develop/CONTRIBUTING.md
Expand Down
6 changes: 4 additions & 2 deletions Downloads.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## PDF Manuals

- [Cacti development manual](resource/pdf/cacti-manual.pdf): A snapshot of the
- [Cacti development manual][manual-pdf]: A snapshot of the
current development manual, with a contents list, bookmarks, screenshots,
and links between chapters. It documents the unreleased Cacti 1.3 series.
- [ReportIt 3.0 development manual](resource/pdf/manual_reportit_3.0.pdf):
Expand All @@ -13,7 +13,7 @@
[The original ReportIt 0.6.1 PDF](resource/pdf/manual_reportit.pdf)
remains available as a historical reference.

The [build manifest](resource/pdf/build_manifest.json) records source hashes,
The [build manifest][pdf-manifest] records source hashes,
build date, tool versions, and PDF checksums. It identifies the documentation
base and the exact Markdown content used, including changes in this branch.
Use the [online manual](README.md) for subsequent documentation updates.
Expand Down Expand Up @@ -78,6 +78,8 @@ native libraries.
[traffic-template]: resource/xml/cacti_data_query_php_interface_traffic.xml
[reportit-source]:
<https://github.com/Cacti/plugin_reportit/blob/86726fc5eff51e23baf18834f69da2aa0b1efa77/ReportIt%20Documentation.docx>
[manual-pdf]: https://github.com/Cacti/documentation/releases/download/manuals-develop/cacti-manual.pdf
[pdf-manifest]: https://github.com/Cacti/documentation/releases/download/manuals-develop/cacti-manual-manifest.json

---

Expand Down
42 changes: 26 additions & 16 deletions Other-Manuals.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ styles. They do not import the website's visual design.

## Complete maintained manuals

- [PDF manual](resource/pdf/cacti-manual.pdf), with all current main chapters,
- [PDF manual][manual-pdf], with all current main chapters,
bookmarks, screenshots, and links between chapters.
- [UTF-8 text manual](resource/manuals/manual.txt), with the same main chapters,
- [UTF-8 text manual][manual-text], with the same main chapters,
command examples, image descriptions, and full link destinations.
- [HTML manual publication](resources/build/HTML-Manual.md), including all
chapters and legacy chapter URLs.
Expand All @@ -27,14 +27,14 @@ welcome; platform checks and runtime limitations still apply.

| Guide | Read online | PDF | Text |
| --- | --- | --- | --- |
| German installation and operation | [Deutsch](resources/manuals/Guide-de.md) | [PDF](resource/manuals/cacti-guide-de.pdf) | [Text](resource/manuals/cacti-guide-de.txt) |
| Turkish installation and operation | [Türkçe](resources/manuals/Guide-tr.md) | [PDF](resource/manuals/cacti-guide-tr.pdf) | [Text](resource/manuals/cacti-guide-tr.txt) |
| Linux installation | [English](resources/manuals/Install-linux.md) | [PDF](resource/manuals/install-linux.pdf) | [Text](resource/manuals/install-linux.txt) |
| Russian UNIX installation | [Русский](resources/manuals/Install-ru-unix.md) | [PDF](resource/manuals/install-ru-unix.pdf) | [Text](resource/manuals/install-ru-unix.txt) |
| Russian Windows installation | [Русский](resources/manuals/Install-ru-windows.md) | [PDF](resource/manuals/install-ru-windows.pdf) | [Text](resource/manuals/install-ru-windows.txt) |
| Windows installation | [English](Installing-Under-Windows.md) | [PDF](resource/manuals/install-windows.pdf) | [Text](resource/manuals/install-windows.txt) |
| Migration from Solaris | [English](resources/manuals/Migrate-solaris.md) | [PDF](resource/manuals/migrate-solaris.pdf) | [Text](resource/manuals/migrate-solaris.txt) |
| Development database schema | [Reference](resources/manuals/Schema-Reference.md) | [PDF](resource/manuals/schema-reference.pdf) | [Text](resource/manuals/schema-reference.txt) |
| German installation and operation | [Deutsch](resources/manuals/Guide-de.md) | [PDF](https://github.com/Cacti/documentation/releases/download/manuals-develop/cacti-guide-de.pdf) | [Text](https://github.com/Cacti/documentation/releases/download/manuals-develop/cacti-guide-de.txt) |
| Turkish installation and operation | [Türkçe](resources/manuals/Guide-tr.md) | [PDF](https://github.com/Cacti/documentation/releases/download/manuals-develop/cacti-guide-tr.pdf) | [Text](https://github.com/Cacti/documentation/releases/download/manuals-develop/cacti-guide-tr.txt) |
| Linux installation | [English](resources/manuals/Install-linux.md) | [PDF](https://github.com/Cacti/documentation/releases/download/manuals-develop/install-linux.pdf) | [Text](https://github.com/Cacti/documentation/releases/download/manuals-develop/install-linux.txt) |
| Russian UNIX installation | [Русский](resources/manuals/Install-ru-unix.md) | [PDF](https://github.com/Cacti/documentation/releases/download/manuals-develop/install-ru-unix.pdf) | [Text](https://github.com/Cacti/documentation/releases/download/manuals-develop/install-ru-unix.txt) |
| Russian Windows installation | [Русский](resources/manuals/Install-ru-windows.md) | [PDF](https://github.com/Cacti/documentation/releases/download/manuals-develop/install-ru-windows.pdf) | [Text](https://github.com/Cacti/documentation/releases/download/manuals-develop/install-ru-windows.txt) |
| Windows installation | [English](Installing-Under-Windows.md) | [PDF](https://github.com/Cacti/documentation/releases/download/manuals-develop/install-windows.pdf) | [Text](https://github.com/Cacti/documentation/releases/download/manuals-develop/install-windows.txt) |
| Migration from Solaris | [English](resources/manuals/Migrate-solaris.md) | [PDF](https://github.com/Cacti/documentation/releases/download/manuals-develop/migrate-solaris.pdf) | [Text](https://github.com/Cacti/documentation/releases/download/manuals-develop/migrate-solaris.txt) |
| Development database schema | [Reference](resources/manuals/Schema-Reference.md) | [PDF](https://github.com/Cacti/documentation/releases/download/manuals-develop/schema-reference.pdf) | [Text](https://github.com/Cacti/documentation/releases/download/manuals-develop/schema-reference.txt) |

The German and Turkish appendices include every current main manual chapter.
Installation editions include the complete platform, first-graph,
Expand All @@ -44,7 +44,7 @@ guide rather than an unverified new-install procedure. The Windows guides
explain the current development dependency restriction before any install
instructions.

The [schema SQL](resource/manuals/cacti-schema.sql) contains only the pinned
The [schema SQL][schema-sql] contains only the pinned
upstream `CREATE TABLE` statements. It is a reference, not an installer or
upgrade script. It has no seed data and does not describe plugin tables.
Use the schema supplied with your exact Cacti release for installation.
Expand Down Expand Up @@ -85,17 +85,27 @@ documents are not copied or translated into the new guides.
Follow [manual publication][publication] to rebuild and
validate every edition. The [edition manifest][editions-manifest]
records exact sources and checksums. The PDF builder also records its locked
toolchain in [the PDF manifest](resource/pdf/build_manifest.json).
toolchain in [the PDF manifest][pdf-manifest].

CI publishes review artifacts; it does not deploy the public file host.
Maintainers should publish the new editions under distinct versioned names,
link this index from the download page, and retain the original archive URLs.
CI rebuilds and verifies every edition after each change to `develop` and
publishes the results as assets of the
[development manual editions release][release]. The generated files are not
committed to this repository.

Maintainers who mirror the editions on the public file host should publish
them under distinct versioned names, link this index from the download page,
and retain the original archive URLs.
Publish the main manual separately from the historic `manual.pdf` and
`manual.txt` names so an existing archive citation keeps its meaning.

[publication]: resources/build/Other-Manuals.md
[release]: https://github.com/Cacti/documentation/releases/tag/manuals-develop
[pdf-manifest]: https://github.com/Cacti/documentation/releases/download/manuals-develop/cacti-manual-manifest.json
[manual-pdf]: https://github.com/Cacti/documentation/releases/download/manuals-develop/cacti-manual.pdf
[manual-text]: https://github.com/Cacti/documentation/releases/download/manuals-develop/manual.txt
[schema-sql]: https://github.com/Cacti/documentation/releases/download/manuals-develop/cacti-schema.sql
[inventory]: resources/manuals/archive-inventory.json
[editions-manifest]: resource/manuals/build-manifest.json
[editions-manifest]: https://github.com/Cacti/documentation/releases/download/manuals-develop/editions-manifest.json
[stable]: https://github.com/Cacti/documentation/blob/1.2.x/README.md
[old-de]: https://files.cacti.net/docs/contrib/Cacti-Doku_german.pdf
[old-tr]: https://files.cacti.net/docs/contrib/Cacti-El-Kitab.pdf
Expand Down
Loading