This guidance is hosted on GitHub Pages.
A compendium of open-source guidance which aims to share the benefits, risks and a summarised strategy for open-source coding.
This documentation is written and built using Quarto - an open-source scientific and technical publishing system. To work with Quarto, you will need to install the Quarto CLI (Command Line Interface). How this is done is dependent on the system you are using:
- Internal to ONS: Installation is possible via ServiceNow. Select 'I Want Something' > Computer Software - Add / Transfer / Remove > Complete and submit the request form.
- External to ONS: Follow the Quarto Getting Started page for more details.
If you are new to Quarto, check out Quarto's tutorials and detailed documentation for further information.
In addition to the Quarto CLI, and if VS Code is your integrated development environnement of choice, a useful (and completely optional) VS Code extension is available. This provides additional functionality to VS Code that will make previewing and rendering using Quarto easier. Another useful VS code extension is the Microsoft verified Code Spell Checker. This is useful when editing documentation within VS code since it offers basic spell checking capability. Note: it is recommended you configure the settings of this extension to only work with a subset of file types you want to be spell checked (e.g., .md and .qmd files only).
At it's core, editing this set of documentation means writing in markdown within a set of .qmd files. The table below summarises the current structure of the .qmd files:
| .qmd file | description |
|---|---|
index.qmd |
The main documentation landing page. |
general-considerations/guidance.qmd |
A page in which general considerations for working in an open-source environment are shared. |
overview/references.qmd |
A page that shares all sources used to build this documentation. |
private_to_public/guidance.qmd |
A page dedicated summarising a strategy for transitioning private repositories into the public domain. |
Whilst editing the documentation, from root directory you can call:
quarto previewfrom the command line (or use the VS Code button at the top right hand corner of the .qmd file) to open a live preview locally on your machine.
The main configuration is controlled via _quarto.yml. Here, numerous options are available from fixing the layout to adding new pages. You can find out more about these options on Quarto's project basics page.
In addition to the main configuration, it is possible to create dynamic/global variables that can then be used throughout the documentation. This is done within _variables.yml. See the variables section of Quarto's documentation for more details.
This documentation is built from and adds to existing sources of information and guidances on open-sourcing codebases. Therefore, referencing/citations are an important part of this documentation.
Quarto handles this automatically using citation markdown. This can simply be used anywhere within .qmd files to reference a source.
The sources themselves are stored in the BibLaTeX file bibliography/references.bib. See BibTeX's guide for more information on the required referencing syntax.
A CSL (Citation Style Language) file (bibliography/ieee.csl) is used to control the format and layout of the references once the pages are rendered. At the moment, the IEEE format has been chosen for it's simplicity and conciseness, but other CSL formats exist, with their complementary files being provided by the Citation Style Language Project.
Assets (such as images) can be added to the assets/ directory. There is a subdirectory within this specifically for images, to keep them all in one common place. Quarto then reads these in as figrues using a relative (to the root) reference to the image.
Once you are happy with the content and any modifications you have made, the documentation can be rendered. Please note that manual renderring is not a requirement of hosting this guidance on GitHub Pages. This can be done by calling:
quarto renderfrom the command line at the root directory (or use the VS Code button at the top right hand corner of the .qmd file). This will build the documentation, storing it within the docs folder. Feel free to render a local copy for styling etc, but please do not commit html files to the repository.
- If you'd like to raise an issue, please check against the current list of issues first.
- PRs are most welcome. Link your PR to an existing issues where possible.
- Please do not commit HTML to the repo. CI is setup to handle rendering & publishing.
The guidance here has been carefully adjusted to ensure that Web Accessibility guidelines are met. Our guidance must be useful to everyone who has a need to use it. When contributing, please check for these common accessibility problems:
- Don't use italic or strikethrough text.
- Ensure all images have descriptive alt text.
- Only use image tags, markdown syntax renderring cannot be relied upon to present alt text as required by WCAG guidance.
- This repo is using the actions produced by the quarto dev community.
- Pubilcation happens from the gh-pages branch. This branch should not be manually updated.
- PRs accepted to the main branch will use CI to bump gh-pages, automatically renderring HTML & publishing to Pages.
- Ensure the repository settings under Settings > Pages > Build & deployment remain as: Deploy from a branch and pointing to the root of the gh-pages branch.
At the Data Science Campus we apply data science, and build skills, for public good across the UK and internationally. Get in touch with the Campus at [email protected].
The code, unless otherwise stated, is released under the MIT Licence.
The documentation for this work is subject to © Crown copyright and is available under the terms of the Open Government 3.0 licence.