Add docs for ansible-creator (#43)

* add gifs for documentation

* add different sections in the doc

* add config settings for building docs

* add words to dictionary

* update gifs to high res

* fix lint

.config/dictionary.txt

@@ -10,6 +10,7 @@ argspec
 argvalues
 astimezone
 autorefs
+autosectionlabel
 basesystem
 BUILDDIR
 caplog
@@ -118,6 +119,7 @@ scaffolders
 SCAP
 scrollback
 sectionauthor
+seealso
 setuptools          # Used in _version.pyi
 setval
 SIGTERM

docs/source/collection_creation.md

@@ -0,0 +1,53 @@
+# Creating ansible collection Using ansible-creator and VS Code Ansible extension
+
+For users who prefer a graphical interface, ansible-creator seamlessly integrates with the [Visual Studio Code (VS Code)](https://code.visualstudio.com/docs) and the [Ansible extension](https://marketplace.visualstudio.com/items?itemName=redhat.ansible) for it, offering an intuitive GUI experience. If the command line is not your preferred method, the extension provides a user-friendly alternative. By navigating to the Ansible section in the VS Code activity bar and selecting "Ansible Creator," users can access a menu-driven interface. This GUI simplifies complex tasks such as initializing Ansible Collections by providing interactive forms for straightforward input. The extension enhances the development experience, offering visual cues and options for users who may find a graphical approach more comfortable and accessible. With ansible-creator in VS Code, you can effortlessly manage your Ansible content without delving into the intricacies of command-line operations.
+
+Here is a detailed guide on creating an ansible collection using the ansible-creator and VS Code Ansible extension:
+
+## Step 1: Installing ansible-creator in the Environment
+
+1. Open VS Code and click on the Ansible icon in the activity bar. This action expands and opens the `Ansible Creator` section. Click on _"Get Started"_ to access the Menu page of ansible-creator in the editor.
+
+2. On the Menu page the `System Requirements` box will view details about the current environment, including ansible, Python, and ansible-creator. If ansible-creator is not installed, proceed to the next step.
+
+3. Install ansible-creator or switch to an environment where ansible-creator is already installed. Ensure that all requirements in the `system requirements` box display green ticks to signify a ready environment.
+
+![refresh](./media/refresh.gif){width=900px align=center}
+
+## Step 2: Initializing Collection by Filling an Interactive Form
+
+1. From the menu page, click on `Initialize a collection` to access the _"Init"_ interface in the editor, providing an interactive form.
+
+2. Enter the namespace and the collection name. You can review the format of your collection name as you type.
+
+3. Specify the initialization path. You can utilize the folder icon to open the folder-browser dialog and select the desired location for the collection.
+
+```{Note}
+Use the expanded path; shorthand notations are not supported.
+```
+
+![open-folder](./media/open-folder.gif){width=900px align=center}
+
+4. Set the verbosity of the output using the options in the dropdown.
+
+5. Optionally, you can log the output to a file by checking the `Log output to a file` option. This reveals additional options related to logging, including selecting the log file, choosing to append to the file, and setting the file logging level.
+
+![log-to-file](./media/log-to-file.gif){width=900px align=center}
+
+6. To re-scaffold an existing collection, check the `Force` box. This removes the existing content in the collection and freshly scaffolds it with the same name.
+
+7. Finally, after reviewing the details, click the `Create` button, and within milliseconds, the collection will be scaffolded in the specified location.
+
+8. You can review the logs or open the log file (if created) in the VS Code Editor for further scrutiny.
+
+![open-log-file](./media/open-log-file.gif){width=900px align=center}
+
+## Step 3: Leveraging the Extension's ability to Interact with the New Collection
+
+1. Once the scaffolding is complete, you can directly add the collection to your current workspace by clicking the provided `Open Collection` button. This will additionally open the `galaxy.yml` file in a new tab in the editor.
+
+![open-collection](./media/open-collection.gif){width=900px align=center}
+
+2. Start developing the content within the newly scaffolded collection.
+
+3. A playbook adjacent to the collection will automatically enable language service features such as syntax-highlighting, auto-completion, linting, and go-to definitions. You can leverage these features to enhance the development process seamlessly.

docs/source/conf.py

@@ -1,4 +1,8 @@
-# Configuration file for the Sphinx documentation builder.  # noqa: D100
+"""The ansible-creator Documentation builder source."""
+
+# pylint: disable=redefined-builtin,invalid-name
+
+# Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
@@ -14,20 +18,32 @@
 # import sys    # noqa: ERA001
 # sys.path.insert(0, os.path.abspath('.'))  # noqa: ERA001
 
-
 # -- Project information -----------------------------------------------------
 
-PROJECT = "Ansible Creator"
-COPYRIGHT = "2023, Ansible"
-AUTHOR = "Ansible"
+project = "Ansible Creator"
+copyright = "2023, Ansible"  # noqa: A001   # pylint: disable=redefined-builtin
+author = "Ansible"
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["myst_parser", "sphinx.ext.duration", "sphinx_ansible_theme"]
+extensions = [
+    "myst_parser",
+    "sphinx.ext.duration",
+    "sphinx_ansible_theme",
+]
+
+myst_enable_extensions = [
+    "attrs_inline",
+]
+
+autosectionlabel_prefix_document = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -44,8 +60,15 @@
 # a list of builtin themes.
 #
 html_theme = "sphinx_ansible_theme"  # pylint: disable=invalid-name
+html_title = "Ansible Creator Documentation"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+
+html_theme_options = {
+    "display_version": False,
+    "titles_only": False,
+    "documentation_home_url": "https://ansible-creator.readthedocs.io/en/latest/",
+}

docs/source/developer_contribution.md

@@ -0,0 +1,31 @@
+# Contributing to ansible-creator
+
+To actively contribute to the development and enhancement of ansible-creator, your participation is valued. Please use pull requests on a branch of your own fork. After [creating your fork on GitHub](https://docs.github.com/en/get-started/quickstart/contributing-to-projects), you can do:
+
+```console
+$ git clone --recursive [email protected]:your-name/ansible-creator
+$ cd ansible-creator
+$ git checkout -b your-branch-name
+
+# DO SOME CODING HERE
+
+$ git add your new files
+$ git commit -v
+$ git push origin your-branch-name
+```
+
+You will then be able to create a pull request from your commit. This will initiate the process of reviewing and merging your contributions.
+
+For contributions affecting core functionality (i.e., anything except docs or examples), ensure to include corresponding tests that validate the changes. Even if you're not providing a code fix, your input is valuable—feel free to raise [issues](https://github.com/ansible/ansible-creator/issues) in the repository.
+
+## Standards
+
+All pull requests undergo automated tests. To ensure that your changes align with project standards, run checks locally before pushing commits using [tox](https://tox.wiki/en/latest/).
+
+## Get in touch
+
+Connect with the ansible-creator community through the [GitHub discussions forum](https://github.com/ansible/ansible-creator/discussions). For real-time interactions, join the `#ansible-devtools` IRC channel on libera.chat or the Matrix room [#devtools:ansible.com](https://matrix.to/#/#devtools:ansible.com). Explore the full list of Ansible IRC and Mailing list options on the Ansible Communication page. Release announcements will be made to the Ansible Announce list. If you encounter security-related concerns, report them via email to [[email protected]](mailto:[email protected]).
+
+## Code of Conduct
+
+As with all Ansible projects, adhere to the [Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) to foster a respectful and inclusive collaborative environment. Your contributions, feedback, and engagement are essential to the success of ansible-creator.

docs/source/index.md

@@ -3,11 +3,30 @@
 % You can adapt this file completely to your liking, but it should at least
 % contain the root `toctree` directive.
 
-```{include} ../../README.md
-:relative-images:
-```
+# Welcome to Ansible-Creator Documentation
+
+The `ansible-creator` is a Command-Line Interface (CLI) tool designed for effortlessly scaffolding all your Ansible content. Whether you are initializing an Ansible Collection or creating the framework for specific plugins, this tool streamlines the process with efficiency and precision based on your requirements.
+
+This documentation serves as a detailed guide for using ansible-creator, emphasizing the 'init' functionality for initializing Ansible Collections. Stay tuned for updates on the 'create' branch that will bring new features to enhance your Ansible workflow.
 
 ```{toctree}
 :caption: 'Contents:'
 :maxdepth: 2
+
+self
+installation_usage
+collection_creation
+developer_contribution
+```
+
+## Upcoming Features
+
+The `create` command is currently under development which will allow you scaffold ansible plugins of your choice.
+
+```{Tip}
+Switch to the create [create branch](https://github.com/ansible/ansible-creator/tree/create) of the project to try it out!
 ```
+
+## Licensing
+
+**ansible-creator** is licensed under the GNU General Public License v3.0 or later. Refer to the [LICENSE](https://www.gnu.org/licenses/gpl-3.0.txt) file for the full text.

docs/source/installation_usage.md

@@ -0,0 +1,140 @@
+# Installation and Usage
+
+ansible-creator provides two main functionalities: `init` and `create`. The `init` command allows you to initialize an Ansible Collection, while `create` command allows you scaffold ansible plugins of your choice.
+
+## Installation
+
+To install ansible-creator, use the following pip command:
+
+```console
+$ pip install ansible-creator
+```
+
+## CLI Usage
+
+The Command-Line Interface (CLI) for ansible-creator provides a straightforward and efficient way to interact with the tool. Users can initiate actions, such as initializing Ansible Collections, through concise commands. The CLI is designed for simplicity, allowing users to execute operations with ease and without the need for an extensive understanding of the tool's intricacies. It serves as a flexible and powerful option for users who prefer command-line workflows, enabling them to integrate ansible-creator seamlessly into their development processes.
+
+```{seealso}
+Command line not your preferred method? You can also leverage the GUI interface within VS Code's Ansible extension that offers a more visually intuitive experience of ansible-creator. See here: {doc}`collection_creation`
+```
+
+### General Usage
+
+Get an overview of available commands and options by running:
+
+```console
+$ ansible-creator --help
+```
+
+### Initialize Ansible Collection (`init` subcommand)
+
+The `init` command enables you to initialize an Ansible Collection to create a foundational structure for the project. Use the following command template:
+
+```console
+$ ansible-creator init <collection-name> --init-path <path>
+```
+
+#### Positional Argument(s)
+
+| Parameter  | Description                                                          |
+| ---------- | -------------------------------------------------------------------- |
+| collection | The name of the collection in the format `<namespace>.<collection>`. |
+
+#### Optional Arguments
+
+| Parameter                 | Description                                                                                           |
+| ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| -h, --help                | Show help message and exit.                                                                           |
+| --na, --no-ansi           | Disable the use of ANSI codes for terminal color.                                                     |
+| --lf, --log-file <file>   | Log file to write to.                                                                                 |
+| --ll, --log-level <level> | Log level (notset, debug, info, warning, error, critical) for file output.                            |
+| --la, --log-append <bool> | Append to log file.                                                                                   |
+| --json                    | Output messages as JSON.                                                                              |
+| -v, --verbose             | Give more CLI output. Option is additive and can be used up to 3 times.                               |
+| --init-path <path>        | The path where the skeleton collection will be scaffolded (default is the current working directory). |
+| --force                   | Force re-initialize the specified directory as an Ansible collection.                                 |
+
+#### Example
+
+```console
+$ ansible-creator init testns.testname --init-path $HOME/collections/ansible_collections
+```
+
+This command will scaffold the collection `testns.testname` at `/home/ansible-dev/collections/ansible_collections`
+
+#### Generated Ansible Collection Structure
+
+Running the init command generates an Ansible Collection with a comprehensive directory structure. Explore it using:
+
+```console
+$ tree -lla /home/ansible-dev/collections/ansible_collections
+.
+├── CHANGELOG.rst
+├── changelogs
+│   └── config.yaml
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING
+├── docs
+│   ├── docsite
+│   │   └── links.yml
+│   └── .keep
+├── extensions
+│   ├── eda
+│   │   └── rulebooks
+│   │       └── rulebook.yml
+│   └── molecule
+│       ├── integration_hello_world
+│       │   └── molecule.yml
+│       └── utils
+│           ├── playbooks
+│           │   ├── converge.yml
+│           │   └── noop.yml
+│           └── vars
+│               └── vars.yml
+├── galaxy.yml
+├── .github
+│   └── workflows
+│       └── test.yml
+├── .isort.cfg
+├── LICENSE
+├── MAINTAINERS
+├── meta
+│   └── runtime.yml
+├── plugins
+│   ├── action
+│   │   └── __init__.py
+│   ├── cache
+│   │   └── __init__.py
+│   ├── filter
+│   │   ├── hello_world.py
+│   │   └── __init__.py
+│   ├── inventory
+│   │   └── __init__.py
+│   ├── modules
+│   │   └── __init__.py
+│   ├── module_utils
+│   │   └── __init__.py
+│   ├── plugin_utils
+│   │   └── __init__.py
+│   ├── sub_plugins
+│   │   └── __init__.py
+│   └── test
+│       └── __init__.py
+├── .pre-commit-config.yaml
+├── .prettierignore
+├── pyproject.toml
+├── README.md
+├── tests
+│   ├── .gitignore
+│   ├── integration
+│   │   ├── __init__.py
+│   │   ├── targets
+│   │   │   └── hello_world
+│   │   │       └── tasks
+│   │   │           └── main.yml
+│   │   └── test_integration.py
+│   └── unit
+│       └── .keep
+└── .vscode
+    └── extensions.json
+```