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 [email protected]:felixfontein/mynamespace.mycollection.git ~/collections/ansible_collections/mynamespace/mycollection
$ ansible localhost -m mynamespace.mycollection.test

alternatively:

$ mkdir ~/demo/ && cd ~/demo
$ git clone [email protected]: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:
- 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

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

Docs presentation