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. (See sample CRM issue.)