make webdocs for custom collection

[Dhiwakar Ravikumar]

Hi

I have developed a collection of modules on my local setup.

Now, I've already verified that the CLI docstrings for the modules are printing correctly 

by running

ansible-doc

Next, I wanted to generate the HTML webdoc file.

So I followed the steps listed here.

https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html

Installing prerequisites via yum (CentOS)

Due to dependencies (for example ansible -> paramiko -> pynacl -> libffi):

sudo yum check-update sudo yum update sudo yum group install "Development Tools" sudo yum install python3-devel openssl-devel libffi libffi-devel

Creating a development environment (platform-agnostic steps)

1. Clone the Ansible repository: $ git clone https://github.com/ansible/ansible.git

2. Change directory into the repository root dir: $ cd ansible

3. Create a virtual environment: $ python3 -m venv venv (or for Python 2 $ virtualenv venv. Note, this requires you to install the virtualenv package: $ pip install virtualenv)

4. Activate the virtual environment: $ . venv/bin/activate

5. Install development requirements: $ pip install -r requirements.txt

6. Run the environment setup script for each new dev shell process: $ . hacking/env-setup

Now, I manually copied my collection of modules to the location mentioned in STEP 3 below

To check the HTML output of your module documentation:

1. Ensure working development environment.

2. Install required Python packages (drop ‘–user’ in venv/virtualenv):

   pip install --user -r requirements.txt pip install --user -r docs/docsite/requirements.txt

3. Ensure your module is in the correct directory: lib/ansible/modules/$CATEGORY/mymodule.py.

4. Build HTML from your module documentation: MODULES=mymodule make webdocs

I then tried to find all .html files on the setup, I can't find the HTML file for the modules in my collection.

Can someone please help me figure out if I'm doing it right ? 

[Felix Fontein]

Hi,

instead of trying to force ansible's docsite build to build your
module/plugin docs for your collection, you could simply create a new
docsite:

1. Install antsibull (https://pypi.org/project/antsibull/)
2. Create a new directory /foo/bar
3. Run
antsibull-docs sphinx-init --use-current \
--dest-dir /foo/bar \
namespace.name
where <namespace.name> is the name of your collection
4. Use the generated requirements.txt to install the requirements
needed (in a venv or globally, whatever you prefer)
5. Use the generated shell script to build the docsite

This assumes you have ansible-core installed, and that your collection
is in a path where ansible-core will find it
(https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths).

Best,
Felix

> I have developed a collection of modules on my local setup.
> Now, I've already verified that the CLI docstrings for the modules
> are printing correctly
> by running
>

> *ansible-doc*

>
> Next, I wanted to generate the HTML webdoc file.
> So I followed the steps listed here.
> https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html
>
>
> Installing prerequisites via yum (CentOS)

> <https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#id3>
> <https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#installing-prerequisites-via-yum-centos>

>
> Due to dependencies (for example ansible -> paramiko -> pynacl ->
> libffi): sudo yum check-update sudo yum update sudo yum group install
> "Development Tools" sudo yum install python3-devel openssl-devel
> libffi libffi-devel Creating a development environment
> (platform-agnostic steps)

> <https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#id4>
> <https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#creating-a-development-environment-platform-agnostic-steps>
> 1.

>
> Clone the Ansible
> repository: $ git clone https://github.com/ansible/ansible.git

> 2.

>
> Change directory into the repository root dir: $ cd ansible

> 3.

>
> Create a virtual environment: $ python3 -m venv venv (or for
> Python 2 $ virtualenv venv. Note, this requires you to install the
> virtualenv package: $ pip install virtualenv)

> 4.

>
> Activate the virtual environment: $ . venv/bin/activate

> 5.

>
> Install development requirements: $ pip install -r requirements.txt

> 6.

>
> Run the environment setup script for each new dev shell
> process: $ . hacking/env-setup
>
>
> Now, I manually copied my collection of modules to the location
> mentioned in STEP 3 below
>
> To check the HTML output of your module documentation:
>

> 1.
>
> Ensure working development environment
> <https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#environment-setup>
> .
> 2.

>
> Install required Python packages (drop ‘–user’ in venv/virtualenv):
> pip install --user -r requirements.txt pip install --user -r
> docs/docsite/requirements.txt

> 3.

>
> Ensure your module is in the correct directory:
> lib/ansible/modules/$CATEGORY/mymodule.py.

> 4.

>
> Build HTML from your module documentation: MODULES=mymodule make
> webdocs
>
> I then tried to find all .html files on the setup, I can't find the
> HTML file for the modules in my collection.
>
> Can someone please help me figure out if I'm doing it right ?
>

--
Felix Fontein -- fe...@fontein.de -- https://felix.fontein.de/