OCDS documentation tasks

See also

Migrate OCDS documentation to a new server

Add a new language

1. In salt/apache/files/sites/docs.conf.include, add the new language in the options variable.

2. In tests/test_docs.py, update the languages variable.

Add a new minor version

Below, substitute {root}, {current-minor-branch} and {old-minor-branch}. For example: ppp, 1.1 and 1.0.

1. Edit salt/apache/files/docs/robots.txt

2. If the profile has a version, add:

   Disallow: /profiles/{root}/{current-minor-branch}
   

3. If the profile has older minor versions, also add, for each old minor version:

   Disallow: /profiles/{root}/{old-minor-branch}
   

Publish draft documentation

To configure a documentation repository to push builds to the server:

1. Access the repository’s Settings tab

2. Click Secret and variables

3. Click Actions

4. Set the private key:

   1. Click New repository secret

   2. Set Name to “PRIVATE_KEY”

   3. Set Value to the contents of salt/private/keys/docs_ci

   4. Click Add secret

5. Set the Elasticsearch password:

   1. Click New repository secret

   2. Set Name to “ELASTICSEARCH_PASSWORD”

   3. Set Value to the password of the manage user in the pillar/private/docs.sls file

   4. Click Add secret

Publish released documentation

Follow the OCDS Development Handbook’s deployment guide.

1. Update this repository

Note

You can skip this step if you are not releasing a new major, minor or patch version.

Below, substitute {root}, {latest-branch}, {dev-branch}, {formatted-dev-branch}, {version} and {name}. For example: ppp, latest, 1.0-dev, 1.0 Dev, 1.0.0.beta and OCDS for PPPs.

If this is the first numbered version of a profile:

1. Update salt/docs/robots.txt.

2. In salt/apache/files/sites/docs.conf.include, add the profile’s latest branch, minor series and languages in the options variable.

3. In tests/test_docs.py, update the versions, languages and banner_live variables.

4. Add a salt/docs/includes/version-options-profiles-{root}.html file to this repository:

   <option>Version</option>
   <option value="{latest-branch}">{version} ({latest-branch})</option>
   

5. Add a salt/docs/includes/banner_staging_profiles_{root}.html file to this repository:

   <div class="oc-fixed-alert-header">
       This is a development copy of the {name} docs, the <a href="/profiles/{root}/{latest-branch}/en/">latest live version is here</a>.
   </div>
   

Otherwise:

1. In the appropriate salt/docs/includes/version-options*.html file, update the version number in the text of the first option element.

If this is a new major or minor version:

1. In salt/docs/robots.txt, disallow the minor branch and its dev branch, for example:

   Disallow: /1.2
   Disallow: /1.2-dev
   

2. In salt/apache/files/sites/docs.conf.include, add the minor series in the options variable, and add a new Location directive like:

   <Location /1.1/>
       SetEnv BANNER /includes/banner_old.html
   </Location>
   

3. In ocdsindex-exclude.txt, add the base URL of the new version.

4. In tests/test_docs.py, update the versions, banner_live and banner_old variables.

5. In the appropriate salt/docs/includes/banner_staging*.html file and salt/docs/includes/banner_old*.html> file (if any), update the minor series.

6. In the appropriate salt/docs/includes/version-options*.html file, add an option element to the “Live” optgroup for the previous minor series and previous version number, for example:

   <option value="0.9">0.9.2</option>
   

2. Update other repositories

Update the Data Review Tool and any other tools per this spreadsheet.