Upgrade build system to use docs-utils

[infoverload]

Remove old build system

• Check for the presence of bootstrap.sh in the top-level directory and git rm bootstrap.sh if the file's only function is to prepare a Python virtual environment for Sphinx.

• Check for the presence of docs/requirements.txt.

  • Create it if it doesn't exist and run git add docs/requirements.txt.

  • Look for files named like requirements.txt or requirements-docs.txt in the top-level directory, and move any Python packages related to Sphinx or the docs to the docs/requirements.txt file.

    If you're unsure what a package does, you can look it up on PyPI.

  • If any of the requirements files in the top-level directory are now empty, you can git rm the files.

• Check for the presence of bin in the top-level directory and git rm -r bin if the directory's only contents are a file named sphinx.

• Check for the presence of docs/docutils.conf and git rm docs/docutils.conf if the file is present.

Add the new build system

• Copy the contents of the crate-docs-utils docs/Makefile to a file named docs/Makefile in your current repository and run git add docs/Makefile.

• Copy the contents of the crate-docs-utils docs/utils.json to a file named docs/utils.json in your current repository and run git add docs/utils.json.

• Open the file docs/conf.py.

  Normally, this file should have one line that imports a module with a name matching the name of the docs project.

  Remove all other lines, with the exception of config that has been added specifically for novel features that are used in that docs repository.

• Open the file docs/requirements.txt.

  Normally, this file should have one line (with no versioning):

  crate-docs-theme
  

  Remove all other lines, with the exception of modules that have been added specifically for novel features that are used in that docs repository.

Test the build system

• Run cd docs && make dev and fix any issues.

  • You may have to rename files so that they use the .rst extension instead of the .txt extension.

• Check the docs in your browser look okay and fix any issues if not.

• Run cd docs && make check and fix any issues.

Finishing touches

• Copy the contents of the crate-docs-utils .gitignore file to a file named .gitignore at the root of your current repository.

  If the file already exists:

  • If the file is simple, add the content anywhere you like, then sort all lines alphabetically (case-insensitive). Finally, remove duplicate entries and trim the file so it ends with a single empty newline.

  • If the file looks complex (e.g., has been generated by an IDE), insert the new content wherever it makes sense and then remove any duplicate entries.

• Copy the contents of the crate-docs-utils .readthedocs.yml file to a file named .readthedocs.yml at the root of your current repository.

  • If the file already exists, replace it.

• Copy the contents of the crate-docs-utils .travis.yml file to a file named .travis.yml at the root of your current repository.

  If the file already exists:

  • If the rules only test the documentation, replace the whole file.

  • If the rules test something other than the documentation, the rules for testing the documentation need to be integrated with the existing rules and any old rules for testing the documentation need to be removed. (See the crate-admin .travis.yml for an example.)

• Check the DEVELOP.rst file at the root of your current repository.

  • If the file only documents how to build the docs, replace the whole file with the contents of the crate-docs-utils DEVELOP.rst file.

    • Cut the Preparing a release section and any associated link references.

    • Update the URLs used in the link references so that they point to the proper resources (i.e., GitHub, Travis CI, Read The Docs) for the current repository.

  • If the file is more complex than that, integrate the Documentation section from the crate-docs-utils DEVELOP.rst file into the document, replacing any previous information about how to build the docs.

    • Copy over the CI/CD badge definitions (found at the bottom of the file) as well as any link references used by the Documentation section.

    • Merge the link references into one list, sort alphabetically (case-insensitive), and remove any duplicates.

    • Update the URLs used in the link references so that they point to the proper resources (i.e., GitHub, Travis CI, Read The Docs) for the current repository.

Wrap up

• Add all your changes to Git

• Commit your changes to a branch

• Create a new pull request

[nomicode]

this is done