contributor-summit-02-2023-docs-talk.md

Docs presentation

• public Ansible docsite

  • show https://docs.ansible.com/ansible/latest/collections/
  • "we want to have a similar docsite for our collection"

• setup venv and install ansible-core and antsibull-docs in there

  $ python -m venv ~/antsibull-demo-venv
  $ . ~/antsibull-demo-venv/bin/activate
  $ python -m pip install ansible-core antsibull-docs

• create repo with very basic collection (prepared)

  • use prepared repo containing a collection
    • https://github.com/felixfontein/mynamespace.mycollection/
  • show how to check it out 'correctly' so you can use it:

    $ mkdir -p ~/collections/ansible_collections/mynamespace
    $ export ANSIBLE_COLLECTIONS_PATH=~/collections
    $ git clone git@github.com:felixfontein/mynamespace.mycollection.git ~/collections/ansible_collections/mynamespace/mycollection
    $ ansible localhost -m mynamespace.mycollection.test

    alternatively:

    $ mkdir ~/demo/ && cd ~/demo
    $ git clone git@github.com:felixfontein/mynamespace.mycollection.git
    $ cd mynamespace.mycollection
    $ mkdir -p ~/.ansible/collections/ansible_collections/mynamespace
    $ ln -s $(pwd) ~/.ansible/collections/ansible_collections/mynamespace/mycollection
    $ ansible localhost -m mynamespace.mycollection.test

  • show how to look at docs with ansible-doc -t xxx -l / ansible-doc -t xxx foo.bar.xxx

    $ ansible-doc --type module --list mynamespace.mycollection
    $ ansible-doc --type role --list mynamespace.mycollection
    $ ansible-doc --type module mynamespace.mycollection.test
    $ ansible-doc --type role mynamespace.mycollection.a_role

• antsibull-docs itself (basics, setup)

  • demonstrate antsibull-docs sphinx-init:

    first go into the collection checkout directory

    $ mkdir built-docs
    $ antsibull-docs sphinx-init --use-current --squash-hierarchy mynamespace.mycollection --dest-dir built-docs
    $ cd built-docs
    $ ls -la

    Show the files in there.

  • build simple docsite for the collection

    $ python -m pip install -r requirements.txt
    $ ./build.sh

  • Show results

    $ firefox build/html/index.html

• GHA workflow publish

  • https://github.com/ansible-community/github-docs-build
    • Find useful documentation in the Wiki: https://github.com/ansible-community/github-docs-build/wiki
  • set up GH pages
  • add PR workflow: https://github.com/ansible-community/github-docs-build/blob/main/samples/pr-build-and-comment.yml
  • create test PR
  • show result
  • add workflow to publish docsite and PRs:
    • https://github.com/ansible-community/github-docs-build/blob/main/samples/pr-with-publish-to-gh-pages.yml
    • https://github.com/ansible-community/github-docs-build/blob/main/samples/push-with-publish-to-gh-pages.yml
    • don't forget to enable GitHub Pages :)
      • https://github.com/ansible-community/github-docs-build/wiki/Getting-started-with-GitHub-Pages#setting-up-github-pages-for-the-first-time
  • show result, demonstrate PR

• antsibull-docs lint collection docs

  • how to spot mistakes early on:

    first go into the collection checkout directory

    $ antsibull-docs lint-collection-docs
    $ antsibull-docs lint-collection-docs --plugin-docs

  • show some cases that antsibull-docs spots but ansible-test sanity does not (most likely role argspec)

    $ ansible-test --docker -v --test validate-modules
    $ antsibull-docs lint-collection-docs
    $ antsibull-docs lint-collection-docs --plugin-docs

• antsibull-docs itself (extra docs, extra links etc.)

  • show extra docs
    • add in PR so we can see what changes :)
    • the repository is based on https://github.com/ansible-collections/collection_template/, so it already has docs/docsite/links.yml
    • see https://github.com/ansible-collections/collection_template/blob/main/docs/docsite/links.yml for a fully documented example
  • add extra links
    • again add in PR
    • https://github.com/felixfontein/mynamespace.mycollection/blob/main/docs/docsite/links.yml