https://github.com/euroargodev/online_documentation
A template for online documentation
https://github.com/euroargodev/online_documentation
argo-floats documentation template
Last synced: 8 months ago
JSON representation
A template for online documentation
- Host: GitHub
- URL: https://github.com/euroargodev/online_documentation
- Owner: euroargodev
- License: apache-2.0
- Created: 2024-06-26T13:02:24.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-05T12:21:09.000Z (over 1 year ago)
- Last Synced: 2025-02-05T13:23:07.230Z (over 1 year ago)
- Topics: argo-floats, documentation, template
- Language: Python
- Homepage: https://euroargodev.github.io/online_documentation/
- Size: 2.22 MB
- Stars: 0
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# A template for your online documentation
This repository is a template to get you started with building an online documentation.
You see how this documentation is rendered online here: https://euroargodev.github.io/online_documentation
The documentation is built using [Jupyter book](https://jupyterbook.org/en/stable/intro.html) and is hosted/deployed on Github Pages.
* [Usage](#usage)
+ [Create your own repository](#create-your-own-repository)
+ [Enable doc online rendering](#enable-doc-online-rendering)
+ [Update doc configuration parameters](#update-doc-configuration-parameters)
* [☘ Use Green-Coding energy/CO2e measurements](#-use-green-coding-energyco2e-measurements)
+ [Add your documentation IDs in repository secrets](#add-your-documentation-ids-in-repository-secrets)
- [Identify your project (repository)](#identify-your-project-repository)
+ [Edit the `content/_config.yml` ](#edit-the-content_configyml)
You can use this check list to keep track of the procedure. All steps are explained in details below.
- [ ] Create your own repository using this template
- [ ] Enable documentation online rendering (Github Pages)
- [ ] Update documentation content configuration with your own repository data
### Create your own repository
To create your own documentation using this template, you have to clone this repository using the [green button "Use this template" above](https://github.com/new?template_name=online_documentation&template_owner=euroargodev).
More details here:
https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template
### Enable doc online rendering
In the repository you created using this template, go to "Settings", then "Pages" and change the "Source" parameter to "Github Actions".
### Update doc configuration parameters
Edit the `content/_config.yml` file to update parameters with the new repository data.
2 parameters must be updated:
- replace any template ``euroargodev`` occurrences with your own `OWNER` name,
- replace any template ``online_documentation`` occurences with your `` name.
```yml
repository:
url: https://github.com//
extra_footer: |
By the Euro-Argo Dev community using
Jupyter Book.
This work is licensed under a
Creative Commons Attribution 4.0 Generic License.
```
## ☘ Use Green-Coding energy/CO2e measurements
Interested in monitoring the energy consumption and CO2e emission associated with the building and deployment of your documentation ?
The documentation template is equiped to do this, but some parameters must be updated first. Follow these steps:
### Add your documentation IDs in repository secrets
In order to identify your documentation within the [📊 euroargodev overall energy & CO2e metrics](https://metrics.green-coding.io/carbondb-lists.html?company_uuid=4f42f511-4d8d-4d30-9c5e-8490f2c68811), you need to create specific IDs for your project and the Github Action machines.
#### Identify your project (repository)
1. Get a unique ID from https://www.uuidgenerator.net. Copy the generated ID (it should be a string looking like this example: `4374ec28-7bca-4893-9c69-13e638cda063`)
1. On your repository, go to "Settings", then "Secrets and Variables" and click on the green button "New repository secret"
1. Name it `CARBONDB_PROJECT_UUID` and paste the ID you generated in the previous step in the *secret* field, finalize by clicking on the "Add secret" green button.
### Edit the `content/_config.yml`
Once you created you secrets, build the documentation manually by executing the Github action:
Once the documentation is built and deployed, look at the action summary and look for the workflow parameter in the url:
This workflow id must be used in the repository `content/_config.yml` file: replace any template `104534311` occurences with your own `` value:
```yml
```