This is the technical documentation for government services connecting to GOV.UK Verify. It's open to the public and published using GitHub pages.
A general overview of how a government service can connect to Verify is detailed in the the Onboarding Guide which is published and managed separately.
This project uses a documentation tool called Sphinx to convert content written in reStructuredText into HTML.
To build the documentation locally you will need:
- Git to manage versions (you may wish to install the GitHub Desktop GUI)
- Python 2.7 to use Sphinx
If you're using a Mac, you should already have Python installed. You can check by running python --version
in Terminal which should return which version of Python you have installed. For example, Python 2.7.10
.
To publish changes to the public documentation, you'll need access to Jenkins. Contact the Verify development team for access.
While it's possible to make changes directly to the content files using GitHub's built-in editing facilities, checking out the source materials to your local machine has the advantage that you can see any warnings generated when the source reStructuredText files are compiled into HTML. It's also the only way to add binary files such as images.
Clone the repository using the command below.
git clone [email protected]:alphagov/rp-onboarding-tech-docs.git
...or if you're using the desktop client, pick File->Clone Repository and enter the URL:
https://github.com/alphagov/rp-onboarding-tech-docs.git
Once you have Python up and running and a copy of the documentation files, you'll need to install the Pip package manager, which will take care of fetching and installing the remaining dependencies.
Run:
curl https://bootstrap.pypa.io/get-pip.py > get-pip.py
sudo chgrp -R admin /Library/Python/2.7/site-packages/
sudo chmod -R g+w /Library/Python/2.7/site-packages/
python get-pip.py
Then install the remaining dependencies using:
pip install -r requirements.txt
If this fails, it is most likely due to a conflict with the "six" library. This can be cured by running:
pip install --ignore-installed six
then re-running
pip install -r requirements.txt
Before editing any files, you should create a git branch so that your changes are bundled together and can later be merged by an editor (see 'pull requests' later):
Using the Git Desktop Client:
- Click on "Current branch"
- Enter
the-name-of-the-branch
you wish to create (see below for convention) - Click on the blue "Create new branch" button
Using the command line:
git branch <the-name-of-the-branch>
Where the-name-of-the-branch
should be a description of the changes you're making, usually a reference to the Jira ticket to which the change relates, for example "TT-1992-Revise-documentation". You should not use spaces.
When editing or writing new content, you must follow the GOV.UK style guide.
The documents must be in reStructuredText format.
Edit the documentation in the source
folder - this is the root folder for the reStructuredText documentation, which is used to build the HTML pages.
You can preview any changes before you publish them. From the root folder, execute the following command:
make html
If there are any incompatible changes, the output will display warning messages to explain what has gone wrong.
You can then open the output file in your browser from the build/html/
folder to preview your changes.
Once you're happy with your changes, you'll need to commit them to this repository.
You can do this using the commands below or using the GitHub Desktop Client (by pressing the "Commit to " button at the bottom of the "changes" panel).
git add . # adds any new files to your git repo
git commit -m "<enter change description here>" # creates a new 'commit' which contains your changes
git push -u origin <the-name-of-the-branch> # pushes your changes to your forked repository
Any future changes you make on this branch can be pushed with
git push
All changes to documentation must be reviewed before publishing.
This is done by issuing a pull request, which alerts subscribers to the repository that there is a change to be reviewed and merged into the master branch for publication.
- Go to the GitHub repository.
- You should see your branch near the top of the page in a box labeled "Your recently pushed branches".
- There will be a big green button next to it saying "Compare & pull request". Press that button.
- Enter any (optional) comments and press the green "Create pull request" button.
Once your changes are accepted and merged into the master branch, they are placed in the Jenkins build pipeline. This triggers a build job which runs automatically and publishes your changes in the live documentation.
Once built, your changes will be visible in the published documentation.
If you think you have discovered a security issue in this code please email [email protected] with details.
For non-security related bugs and feature requests please raise an issue in the GitHub issue tracker.
Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.
The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.