Add mkdocs scaffolding

[BhattacharjeeSutapa]

SUMMARY

Adding mkdocs scaffolding

Fixes #1359

ISSUE TYPE

• New or Enhanced Feature

So far I am hitting the following error when I try to build the docs locally.

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
              - debugging.md
              - migration.md
WARNING  -  A relative path to 'index.md' is included in the 'nav' configuration, which is not found in the documentation files
INFO     -  Documentation built in 5.62 seconds
INFO     -  [23:55:54] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [23:55:54] Serving on http://127.0.0.1:8000/
WARNING  -  [23:56:02] "GET / HTTP/1.1" code 404

Due to this error, when I open the page, it throws a 404 error. Any help is appreciated. For this reason, I have strict: false so that the site at least serves.

[samccann]

To fix the warning, can you:

1. create docs/index.md
2. add the two existing files to that?

That should build a simple docsite with those two existing files.

[samccann]

Okay looks like we can potentially get away without an index.md file if we follow what was done here -https://github.com/ansible/ansible-language-server/blob/main/mkdocs.yml

[samccann]

@BhattacharjeeSutapa - the following as a requirements.txt file in the docs folder might help avoid having to do an apt install mkdocs...

cairosvg
markdown-exec>=1.0.0
mkdocs-gen-files>=0.4.0
mkdocs-material-extensions>=1.1.1
mkdocs-material>=9.0.6
mkdocs>=1.4.2
mkdocstrings-python>=0.8.3
mkdocstrings>=0.20.0
pillow
pipdeptree>=2.3.3
pymdown-extensions>=9.9.2

Then a pip install -r requirements.txt might work instead of an apt install

[samccann]

@oraNod - can you review this PR when you have the chance?

[oraNod]

Nice work @BhattacharjeeSutapa I can build the site without error. One nit on the uri that allows direct edits on GitHub.

Should this PR include a title and maybe some starter text in "index.md"?

[oraNod]

Suggested change

	edit_uri: blob/main/docs/
	edit_uri: blob/devel/docs/

[oraNod]

Looking good @BhattacharjeeSutapa One final nit is to move that requirements file into the docs directory (docs/requirements.txt). That keeps it separate so you don't wind up installing unneeded packages if you aren't building the docs. Thank you for working so diligently on this!

[BhattacharjeeSutapa]

Looking good @BhattacharjeeSutapa One final nit is to move that requirements file into the docs directory (docs/requirements.txt). That keeps it separate so you don't wind up installing unneeded packages if you aren't building the docs. Thank you for working so diligently on this!

Moved requirements.txt file

[oraNod]

Thank you @BhattacharjeeSutapa

[samccann]

@BhattacharjeeSutapa hey I may not be online at the usual time tomorrow but looks like this PR is failing automated CI testing. In case it doesn't show the error, this is what I'm seeing:

So basically it's saying on that line in the mkdocs.yml file, there is an extra whitespace that you need to delete.

Thanks!

[oraNod]

@TheRealHaoLiu Hi, This PR adds docs scaffolding to build AWX Operator docs with MKDocs and is failing CI with an error related to molecule. Would you mind taking a look at that please? Not sure how to fix that. Thanks.

[BhattacharjeeSutapa]

@BhattacharjeeSutapa hey I may not be online at the usual time tomorrow but looks like this PR is failing automated CI testing. In case it doesn't show the error, this is what I'm seeing:

So basically it's saying on that line in the mkdocs.yml file, there is an extra whitespace that you need to delete.

Thanks!

Hi @samccann two whitespaces have been deleted. Sorry for late update.

[samccann]

@BhattacharjeeSutapa - hey - it took me so long to get back to this that your branch now needs a rebase. If you're unfamiliar with rebasing in git, you can see the basics at https://docs.github.com/en/get-started/using-git/about-git-rebase and ping any of us on the Ansible docs matrix channel if you want more assistance. Note the main branch here is called devel so you'll be rebasing to that.

For me, the typical steps are:
git checkout devel
git fetch devel
git checkout mybranch
git rebase devel

Hopefully you don't get any merge conflicts but if you do, we can help you resolve them in matrix or here if you prefer.
If there are no merge conflicts, the final step is:
git push mybranch -f

[samccann]

@BhattacharjeeSutapa - along with the rebase, can you also add the /site folder to the .gitignore? This will make sure git doesn't try to add the temporary /site files to anyone's PR after they do a mkdocs build.

[oraNod]

@BhattacharjeeSutapa Hi, there are two things needed to pass the Molecule CI tests. First thing is to lint the mkdoc.yaml file. It has a couple of undefined fields and a whitespace issue.

I made the changes in this commit: oraNod@3133f24

You can cherry-pick that or do your own linting in something like VSCode (ctrl+i).

The 2nd thing is that the docs requirements need to be updated. I've made the changes in this commit, feel free to cherry-pick them: oraNod@399a235

After that the Molecule tests should pass (I tested with a PR that includes your commits plus my two: https://github.com/ansible/awx-operator/actions/runs/5387656775/jobs/9779262790?pr=1469)

Hope this helps!

[samccann]

thanks @BhattacharjeeSutapa for working with us to get this merged!