GEOS-DEV / GEOS-DEV/GEOS

[EPIC] Free the documentation

Open
#2,603 2 comments 0 reactions 2 assignees View on GitHub

@MelReyCG is already working on this.

Since Sep 27, 2024.

EPIC
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.