Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rethink documentation organisation. #517

Open
DriesSchaumont opened this issue Aug 18, 2023 · 0 comments
Open

Rethink documentation organisation. #517

DriesSchaumont opened this issue Aug 18, 2023 · 0 comments

Comments

@DriesSchaumont
Copy link
Member

DriesSchaumont commented Aug 18, 2023

Currently, the openpipelines source code and the source quarto .qmd files are split in two repositories. This causes some technical friction when updating the documentation:

  1. When a new version of openpipelines is released, qmd files are rendered and pushed to the website repository using github actions
  2. In the website repository there is a submodule for the openpipeline repo which is used when quarto is executed.

This means that information if flowing two times from the openpipelines repository to the website repository. Additionally, if something in the documentation needs to be changed, it might require either:

  1. A push to the openpipelines repo
  2. A push to the website repo
  3. Changes to to both

A solution to this problem might be to merge the source code for openpipelines and the source code for the website together. The website repository continues to exist, but only to host the rendered htmls. The downsides are that

  1. Care should be taken to make sure that changes in the documentation should not trigger a full build of the components. This could be done with similar code to what we already have
  2. The download size of the repository increases.
  3. This change is not just a copy-paste of the website source code to the openpipelines repo, it might require some work to get everything working again.

The advantages are:

  1. Easier automatic deployment of the documentation
  2. The documentation of openpipelines is versionned together with the pipeline. This could enable a multi-version of the documentation in the future.
  3. Making sure that changes (like updating the viash version) do not cause problems is easier because develop build are possible.
  4. Pull requests for changes in the components/workflows can include changes to the documentation as well, making it easier to keep the documentation up-to-date and gathering all changes in a single PR
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant