AutoKey Documentation

About this repository

This is the repository that builds the AutoKey documentation. If you're a user looking for help with AutoKey, see the AutoKey repository. If you have suggestions for how the documentation can be improved, please create an issue to let us know about them.

Resources

• Built using the Sphinx Python documentation-generator to build the HTML AutoKey documentation files.
• Uses the recommonmark package so that Markdown can be used.
• Uses the sphinx.ext.autodoc extension to import the modules, read the documentation for each function, and automatically generate the API documentation from that.
• Uses the sphinx epytext extension to convert older-style Epydoc documentation format to Sphinx-readable documentation.
• Uses the default sphinx.ext.viewcode extension to insert links to the related source-code.

Basic workflows

• Local workflow:
  • The steps you can take to build and preview the documentation locally:
    1. Clone your fork of the AutoKey documentation repository.
    2. Clone the master branch of the AutoKey repository into the same directory next to the AutoKey documentation clone so that Sphinx can read its Python docstrings.
    3. Install the the project's required dependencies.
    4. Run the local build command. The configuration script will automatically detect the sibling path-structure and compile your documentation in the default automatically-created _build directory.
    5. Open _build/html/index.html in your browser to verify your visual layout changes.
• Remote workflow:
  • The steps GitHub takes to build and deploy the documentation:
    1. Clones the master branch of the AutoKey documentation repository.
    2. Clones the master branch of the AutoKey repository inside of the AutoKey documentation directory so that Sphinx can read its Python docstrings.
    3. Installs the project's required dependencies.
    4. Builds the Sphinx site in the docs directory, which it automatically creates inside of the AutoKey documentation directory. Note that the docs directory is used here instead of the default _build directory so that GitHub Pages can find the files.
    5. Uploads the GitHub Pages deployment package from the docs folder.
    6. Deploys the live documentation as GitHub Pages.
    7. Visit the AutoKey documentation page to see the changes.

Developer and maintenance guides

Several guides are available to provide technical procedures for maintaining the documentation and repository:

• Audit links - Check link integrity and manage URL exceptions in the documentation.
• Build local documentation - Generate the documentation locally and preview the changes.
• Build PDF archives - Generate PDF archives of the documentation for sharing.
• Build zip archives - Generate zipped archives of the HTML documentation for sharing.
• Manual documentation rebuild - Trigger a live documentation update.
• Run local tests - Run local tox compatibility tests on the documentation.
• Simulate the GitHub environment - Create a mock GitHub environment to test if local and remote builds will work.
• Update GitHub Actions - Maintain action and security versions.
• Update dependencies - Keep Python packages up-to-date.
• Update guides - Keep the version references in the guides up-to-date.

ToDo

• Upgrade this repository to use Sphinx syntax instead of the older Epytext syntax. See the reStructuredText Primer for more information on the new markup.
• Consider using the sphinxcontrib-multiversion plugin that supports versioned documentation and seems to be decently well-maintained.
• Move this section to the CONTRIBUTORS.md file once it exists.