docs: overhaul of the documentation - #679
Draft
jfonseca-aneo wants to merge 20 commits into
Draft
jfonseca-aneo wants to merge 20 commits into
jfonseca-aneo wants to merge 20 commits into
Conversation
☂️ Python Coverage
Overall Coverage
New FilesNo new covered files... Modified FilesNo covered modified files...
|
|
Replace the flat guide/usage/api layout with a structured hierarchy: - home/ what-is-armonik-api (moved from guide/index.md) - getting-started/ new stubs for overview and installation - packages/ language package guides (moved from guide/packages/ + guide/cpp.md) - how-to/ usage walkthroughs (renamed from usage/) - api-reference/ generated API docs (renamed from api/, v1.md → proto.md) - releases/ release notes (moved from guide/releases.md) - contributing/ new stub - troubleshooting/ index.md (renamed from troubleshooting.md) Internal cross-references updated in home/, troubleshooting/, and api-reference/.
Update the master toctree in index.rst to reflect all path changes from the content restructure (guide/ → home/packages/releases/, usage/ → how-to/, api/ → api-reference/, troubleshooting.md → index.md). Update breathe_projects in conf.py to point to the new api-reference/cpp/doxygen/xml path.
Update all remaining references from the old content/api/ and content/usage/ paths to their new locations: - .readthedocs.yaml: protoc output and sphinx-apidoc output dirs - Doxyfile: OUTPUT_DIRECTORY - scripts/generate-proto-doc.sh: tmp.md → proto.md - scripts/generate-csharp-doc.sh: csharp/*.md glob - scripts/generate-envvars-doc.sh: OUTPUT_DIR - .docs/README.md: all path examples and section headings
…erated doc output
jfonseca-aneo
force-pushed
the
jf/doc-refactor
branch
from
August 17, 2026 10:48
49f3ab2 to
f2c8078
Compare
…ignore and broken README link tmp.md is a gitignored intermediate from the proto-doc generation step but wasn't excluded from the Sphinx source tree, causing ~900 spurious cross-reference warnings. Also updates .gitignore for the api -> api-reference rename (docfx toc.yml was showing as untracked) and points the troubleshooting page at .docs/README.md instead of a link Sphinx can't resolve (README.md is excluded from the build).
…code fences - Install protobuf/deprecation in the doc venv instead of mocking google/deprecation in autodoc_mock_imports: mocking google.protobuf hung the build indefinitely because protobuf's generated code does import-time metaclass/descriptor work that breaks badly against Sphinx's naive Mock objects. - Fix PythonAPI.rst title underline (was 1 char short). - Tag the three Angular template code fences as html+ng2 instead of html so Pygments doesn't choke on *ngFor/*ngIf/(click) syntax. - Suppress duplicate_declaration.cpp (Doxygen emits a spurious empty duplicate compound for an anonymous namespace nested in armonik::api::common::utils) and ref.python (armonik.common.filter.filter.Filter is deliberately re-exported at two shallower package levels, so autodoc documents it three times and bare `Filter` type hints become ambiguous). 967 -> 10 build warnings.
- packages/cpp.md: remove the fabricated Windows compilation walkthrough
(steps, troubleshooting, conclusion) that contradicted the "script not yet
available" warning sitting in the middle of it; keep prerequisites and the
warning only. Fix grammar and drop redundant `[bash]`/`[PowerShell]` fence
titles that just repeated the language tag.
- how-to/angular-integration.md: fix a dead reference-style link (`[ArmoniK]`
rendering as literal brackets), a GitHub emoji shortcode that doesn't render
in Sphinx (`:x:`), two spots referring to the injected `PartitionsClient` as
`ResultClient`/`ResultsClient` (leftover from a different guide), and
numerous grammar issues including inconsistent "our"/"we" vs "your"/"you"
pronoun use throughout a second-person guide.
- how-to/grpc-secure-python.md: fix prerequisite steps listed out of logical
order, a sentence-fragment heading, and typos.
- releases/index.md: fix "chance" typo'd as "change", subject-verb agreement,
and normalize inconsistent blank lines inside note/warning admonitions.
- packages/{index,web,angular,csharp}.md: fix grammar ("is build" -> "is
built", missing articles/prepositions) and awkward phrasing.
…tent) sphinx-apidoc's default modules.rst -> armonik.rst chain forced 3-4 clicks before reaching real content, since the intermediate package pages mostly just link to their subpackages. Pass -T to skip generating modules.rst, and point PythonAPI.rst at a flat glob toctree (same pattern already used by the C# index), so armonik.client/armonik.common/armonik.worker are one click away like the docfx- and Doxygen-generated references.
…s, consolidate reference nav, fix broken examples
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
A good API documentation should follow these guidelines:
Every code example actually should run as shown. Untested examples are a source of API doc complaints.
Description
[Provide a detailled explanation of the modifications you have made. Link any related issues.]
Testing
[When applicable, detail the testing you have performed to ensure that these changes function as intended. Include information about any added tests.]
Impact
[Discuss the impact of your modifications on ArmoniK. This might include effects on performance, configuration, documentation, new dependencies, or changes in behaviour.]
Additional Information
[Any additional information that reviewers should be aware of.]
Checklist