[EPIC] Free the documentation
@MelReyCG is already working on this.
Since Sep 27, 2024.
- Dominant language
- C++
- Stars
- 287
- Forks
- 109
- Avg merge
- 4d 41m
- Merged PRs (30d)
- 5
Description
Description
This is a proposal to have two repository: one for the documentation (user manual, tutorials, developer guide, doxygen) and one for the source code.
If someone can clone the GEOS source code repository (+ the third party), he should be able to clone a documentation repository.
The goal here is to avoid the annoying commit of generated files like the rst files, xsd file or GeosxConfig.hpp
Do not hesitate to comment
Work Scope
The work that has to be done is essentially on the CI side.
I made a rough sequence diagram with the current workflow (box Build and Test) plus a new step called "actions/artifact" that publishes some files as artifacts of the successful workflow instance.
I added a new workflow called (workflow/doc) with the different steps I imagine necessary to use these artifacts and automate the documentation update.
sequenceDiagram
autonumber
actor Reviewer
actor Developer
Developer->>Github: Open Pull Request
box Build & Test
participant Workflow/ci
participant actions/check_draft
participant actions/check_assigned
participant actions/check_submodules
participant actions/check_code_style
participant Workflow/linux_builds
participant actions/artifact
end
Github->>Workflow/ci: Trigger
Workflow/ci->>actions/check_draft: Check that the PR is not a draft
actions/check_draft-->>Workflow/ci: is not a draft
Workflow/ci->>actions/check_assigned:Check that the PR is assigned
actions/check_assigned-->>Workflow/ci: is assigned
Workflow/ci->>actions/check_submodules: Check that submodules are up to date
actions/check_submodules-->>Workflow/ci: submodules are up to date
Workflow/ci->>actions/check_code_style: Check code style fills the requirements
actions/check_code_style-->>Workflow/ci: Code style is ok
Workflow/ci->>Workflow/linux_builds: Build and test GEOS
Workflow/linux_builds->>actions/artifact: Publish artifacts (schema.xsd and GeosxConfig.hpp)
Workflow/linux_builds->>Workflow/ci: Build and tests ended completed successfully
Reviewer->>Github: Merge Pull Request
Github->>Workflow/doc: Trigger - Pull Request beeing closed with is merged flag
Workflow/doc->>dawidd6/action-download-artifact: Retrieve artifacts from workflow/ci
Workflow/doc->>actions/checkout: Checkout documentation repository
actions/checkout-->>Workflow/doc: Source code is checked out
Workflow/doc->>actions/update_rst_tables: Generating schema-dependent RST files
actions/update_rst_tables-->>Workflow/doc: Files are generated
Workflow/doc->>actions/generate doc: Generate doc
actions/generate doc-->>Workflow/doc: Files are genereated
Workflow/doc->>create pull request: Conditionnaly create a pull request and add it to the merge queue
create pull request-->>Workflow/doc: Command completed successfully
Issues in this EPIC
- Add a new step to current CI that generates the artifacts
- Create a new CI workflow that generates the files for the documentation and test if all is ok
- Create a new repository with the extracted files and make the CI point to it
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.