How the Gemini documentation is compiled
The official Gemini documentation is written in asciidoc and parsed into html using asciidoctor. The html is parsed from the .asciidoc files in the docs folder, and is updated using a GitHub action that runs automatically when there is a commit to the repository. There are separate branches for development ('dev') and released ('main').
The html is served using github pages, as follows:
The file structure within the docs folder is as follows:
- Root docs folder: contains the main .asciidoc (or .adoc) files
- snippets: contains the xml snippets used for code examples
- partials: contains the pages for individual elements that are used to generate the overall datasets and services pages
- includes: contains a global asciidoc configuration file (note there's an includes sub-folder in the partials folder too, for more specific configuration)
- assets: contains fonts and css
These are built from the individual files in the partials folder using the include:: directive. Where content differs between datasets and services, an asciidoctor tag is used to determine which content to use, eg # tag::dataset[] or # tag::service[].
There are two approaches to updating the documentation, depending on whether you wish to edit the files on your local machine or whether you wish to edit the files on GitHub.
- Git and docker on your local computer
- Access to a command prompt
- A GitHub account
Clone this repository and switch (checkout) the dev branch. Navigate to the docs folder and make your changes. Save your file and preview your changes by running the following docker command, which will generate the dataset version of the html:
docker run --rm -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor -a docinfo1 -T templates -E slim '*.asciidoc' '*.adoc'
Note that the first time you run this command it will take a while because it will need to download the asciidoctor docker container. Subsequent runs will be much quicker. Note also that any problems (such as syntax errors) will be output to your command line.
If you need to see a change to the services version then run the same command but substituting -a variant-service.
You can now see your changes by opening the generated html files in a web browser. Once you are happy with your changes:
- Stage the changed files (using
git add), - Commit them (using
git commit -m"your commit message"), - Push them to the dev branch (using
git push origin dev)
It will take a few minutes for the github action to run, but then your changes should be visible at https://agiorguk.github.io/gemini-dev/
- A GitHub account
Log in to GitHub with your GitHub account and switch to the dev branch of this repository:
Navigate to the docs folder and select the file you wish to change. Then select the pencil icon to start editing it:
The editing interface shows the file in unparsed asciidoc format for you to edit, plus a preview tab and a button to cancel changes. Note that the preview tab will not include the full styling:
When you have finished making your changes and have previewed them to ensure there are no obvious errors, scroll to the bottom of the page and provide an informative title and description for the change. Choose the option to commit directly to the dev branch.
It will take a few minutes for the github action to run, but then your changes should be visible at https://agiorguk.github.io/gemini-dev/
The global styling is included in the css, then the text is marked up to show the elements that need styling. There's a good reference to the syntax at https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/ otherwise have a look at the raw version of a page like https://raw.githubusercontent.com/agiorguk/gemini/dev/docs/partials/keyword.asciidoc to see the markup conventions that we're using in this repository.
The live (main) branch is protected from accidental commits. To push changes to it, you need to submit a pull request from the dev branch that will need to be reviewed by another member of the team before it can be merged. You can assign a reviewer as part of the submission process. (To be completed)
Since it's not possible to re-use deploy keys, there are different ways of authenticating the live and dev workflows:
- Uses a deploy key referenced as "secrets.ACTIONS_DEPLOY_KEY"
- Uses an ssh private/public key pair
- See repository settings -> deploy keys for the public key and repository settings -> secrets and variables setting for the private key
- Uses a personal access token referenced as "secrets.API_TOKEN_GITHUB"
- API tokens are generated in a user's personal profile -> settings -> developer settings -> personal access tokens (classic)
- Generate one without an expiry date!
- See repository settings -> secrets and variables