Skip to content

Commit

Permalink
Convert documentation to mkdocs
Browse files Browse the repository at this point in the history
  • Loading branch information
ssbarnea committed Dec 15, 2023
1 parent ad589c5 commit c1a8469
Showing 23 changed files with 174 additions and 150 deletions.
2 changes: 2 additions & 0 deletions .config/docs-requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
mkdocs-ansible[lock]>=0.2.0
pipdeptree>=2.7.1
3 changes: 0 additions & 3 deletions .config/requirements-doc.txt

This file was deleted.

2 changes: 1 addition & 1 deletion .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -1 +1 @@
* @NilashishC
* @NilashishC @ansible/devtools
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -16,3 +16,5 @@ build/
*.tox/

__pycache__/
.cache
_readthedocs
23 changes: 0 additions & 23 deletions .readthedocs.yaml

This file was deleted.

25 changes: 25 additions & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
version: 2

mkdocs:
fail_on_warning: true
configuration: mkdocs.yml

build:
os: ubuntu-22.04
tools:
python: "3.11"
commands:
- pip install --user tox
- python3 -m tox -e docs
python:
install:
- method: pip
path: tox
- method: pip
path: .
extra_requirements:
- docs
submodules:
include: all
recursive: true
2 changes: 1 addition & 1 deletion .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -2,7 +2,7 @@
"[python]": {
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll": true
"source.fixAll": "explicit"
},
"editor.defaultFormatter": "ms-python.black-formatter"
},
Empty file removed docs/.keep
Empty file.
20 changes: 0 additions & 20 deletions docs/Makefile

This file was deleted.

File renamed without changes.
File renamed without changes.
25 changes: 8 additions & 17 deletions docs/source/index.md → docs/index.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,22 @@
% Ansible Creator documentation master file, created by
% sphinx-quickstart on Fri Nov 17 12:47:50 2023.
% You can adapt this file completely to your liking, but it should at least
% contain the root `toctree` directive.
---
hide:
- navigation
- toc
---

# 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!
```
!!! notice

Switch to the create [create branch](https://github.com/ansible/ansible-creator/tree/create) of the project to try it out!

## Licensing

4 changes: 1 addition & 3 deletions docs/source/installation_usage.md → docs/installing.md
Original file line number Diff line number Diff line change
@@ -14,9 +14,7 @@ $ pip install ansible-creator

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`
```
If command line is 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](collection_creation.md).

### General Usage

File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
1 change: 0 additions & 1 deletion docs/source/__init__.py

This file was deleted.

74 changes: 0 additions & 74 deletions docs/source/conf.py

This file was deleted.

117 changes: 117 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
---
# cspell:ignore autohide, autofix
site_name: Ansible Creator Documentation
site_url: https://ansible.readthedocs.io/projects/creator/
repo_url: https://github.com/ansible/ansible-creator
edit_uri: blob/main/docs/
copyright: Copyright © 2023 Red Hat, Inc.
docs_dir: docs
strict: true

# extra_css:
# - stylesheets/extra.css

theme:
name: ansible
features:
- announce.dismiss
- content.action.edit
- content.action.view
- content.code.annotate
- content.code.copy
- content.tabs.link
- content.tooltips
- header.autohide
- navigation.expand
- navigation.footer
- navigation.indexes
- navigation.instant
- navigation.path
- navigation.prune
- navigation.sections
- navigation.tabs
- navigation.tabs.sticky
- navigation.top
- navigation.tracking
- search.highlight
- search.share
- search.suggest
- toc.integrate
extra:
generator: false
social:
- icon: fontawesome/brands/python
link: https://pypi.org/project/ansible-creator/
name: PyPI
- icon: fontawesome/solid/scroll
link: https://github.com/ansible/ansible-creator/releases
name: Releases
- icon: simple/mastodon
link: https://fosstodon.org/@ansible
name: Mastodon
- icon: fontawesome/brands/twitter
link: https://twitter.com/ansible
name: Twitter
- icon: simple/matrix
link: https://matrix.to/#/#devtools:ansible.com
name: Matrix
- icon: fontawesome/solid/comments
link: https://github.com/ansible/ansible-creator/discussions
name: Discussions
- icon: fontawesome/brands/github-alt
link: https://github.com/ansible/ansible-creator
name: GitHub

nav:
- Home:
- home: index.md
- Setup:
- installing.md
- collection_creation.md
- Contributing: contributing.md

exclude_docs: |
_autofix_rules.md
plugins:
- autorefs
- markdown-exec
- material/search:
separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
- material/social
- material/tags
# https://github.com/manuzhang/mkdocs-htmlproofer-plugin
# - htmlproofer

markdown_extensions:
- markdown_include.include:
base_path: docs
- admonition
- def_list
- footnotes
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.superfences
- pymdownx.magiclink:
repo_url_shortener: true
repo_url_shorthand: true
social_url_shorthand: true
social_url_shortener: true
user: facelessuser
repo: pymdown-extensions
normalize_issue_symbols: true
- pymdownx.tabbed:
alternate_style: true
- toc:
toc_depth: 2
permalink: true
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- name: python
class: python
validator: !!python/name:markdown_exec.validator
format: !!python/name:markdown_exec.formatter
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -113,7 +113,7 @@ convention = "pep257"

[tool.setuptools.dynamic]
dependencies = {file = "requirements.txt"}
optional-dependencies.doc = {file = [".config/requirements-doc.txt"]}
optional-dependencies.docs = {file = [".config/docs-requirements.txt"]}
optional-dependencies.test = {file = [".config/requirements-test.txt"]}

[tool.setuptools_scm]
22 changes: 16 additions & 6 deletions tox.ini
Original file line number Diff line number Diff line change
@@ -1,17 +1,18 @@
[tox]
requires =
tox>=4.2
tox>=4.6.3
env_list =
py
lint
no_package = true
skip_missing_interpreters = true
work_dir = {env:TOX_WORK_DIR:.tox}
docs

[testenv]
package = editable

[testenv:py]
description = Run pytest under {basepython} ({envpython})
deps =
-e .[test]
extras =
test
commands =
python --version
pip list
@@ -24,3 +25,12 @@ deps =
pre-commit
commands =
pre-commit run --show-diff-on-failure --all-files

[testenv:docs]
description = Builds docs
package = editable
skip_install = false
extras =
docs
commands =
mkdocs {posargs:build --strict --site-dir=_readthedocs/html/}

0 comments on commit c1a8469

Please sign in to comment.