This repo contains the source code for the quarto technical documentation portal for the Copernicus Data Space Ecosystem.'
| Name | Description | URL |
|---|---|---|
| staging | Branch that contains the next release of the documentation portal | https://documentation-staging.dataspace.copernicus.eu/ |
| publish | Branch that contains the current release of the documentation potal | https://documentation.dataspace.copernicus.eu/ |
Hotfixes to the production documentation portal are done by creating a new PR based on the publish branch.
Once the PR is reviewed and merged, the hotfix changes are automatically merged to both the publish and staging branch.
All other changes are made via a PR on the staging branch.
After reviewing and merging the PR, the changes are automatically pushed to the staging.
For more details click here
To get started, with exploring the documentation locally:
Clone this repository to the local machine:
git clone https://github.com/eu-cdse/documentation.git
To render/preview the documentation locally, one should install Quarto. Detailed instructions for installing Quarto in a preferred editor can be found here.
Here, we import two notebook repositories using git submodules to prevent the need for maintaining identical notebooks in multiple repositories. These submodules serve as additional resources for our documentation. They are:
Quarto allows integrating these notebook contents within the documentation. Moreover, editors must clone these submodules locally to render the documentation.
When cloning this repository, ensure that submodules are also initialized and updated:
git clone --recurse-submodules https://github.com/eu-cdse/notebook-samples.git
For the second submodule, navigate to /APIs/openEO and then clone it:
git clone --recurse-submodules https://github.com/Open-EO/openeo-community-examples.git
Ensure that the submodules are up-to-date and that the latest commit is synced with the documentation repository. To update the submodules to the latest commit in their respective repositories, run:
git submodule update --remote
To avoid merge conflicts when working with submodules:
-
Communicate Changes: Inform other contributors if you're making changes to a submodule to prevent conflicting updates.
-
Sync Submodules: Regularly update submodules to their latest versions to minimize merge conflicts.
-
Cross-check commits: After pushing the latest submodule version to the Publish branch, ensure that the changes are also migrated to the Staging branch.
-
Avoid Direct Edits: Avoid making direct edits within submodule directories from the main repository to prevent unintentional changes.
Once Quarto is installed and the repository with submodules is cloned, navigate to the qmd file host the documentation locally:
quarto render cdse_doc.qmd
or
quarto preview cdse_doc.qmd
Commits within PR are automatically built and rendered to a custom link on the GitHub Pages. After a successfull build of the commits, GitHub Actions will post a new comment with a link to custom documentation portal.
GitHub Actions are set up to automatically merge pull requests into the corresponding branches. In case of a conflict, automatic merge can fail and manual resolution may be needed.
We have incorporated the repository from https://github.com/Open-EO/openeo-community-examples using git submodules, enabling Quarto to integrate the notebook content seamlessly. To facilitate this integration, a 'filter' script (notebook_filter.py) is available that preprocesses the notebooks, ensuring tasks such as configuring the correct openEO URL.
However, it's important to note that the notebooks require thorough review to ensure compatibility across multiple platforms. Moreover, any changes made to the notebooks should be reviewed to maintain consistency.