Add docs

[lkubb]

Per #17 and #15, I'd like to create a centralized documentation around creation and maintenance of Salt extensions, in- and outside of the organization.

This is a draft currently, with many blanks to be filled. Help wanted. :) Thanks a lot to Max Arnold!

Fixes: #17

[max-arnold]

saltstack/salt#66769 (review)

[max-arnold]

Great start!

1. The immediate question I have - where this should live and how users will discover it?

• salt-extension-copier GH pages
• A guide like the User guide or Install guide Could it later grow into a Salt development guide or become part of it?
• The main Salt docs

Pinging @ScriptAutomate to maybe chime in on the above ^^^ (and also whether it makes sense to tweak the theme to look like other guides)

2. I would like to expand the structure a bit to reflect the whole lifecycle

• Add "Documenting your saltext" section (building/previewing docs locally, publishing docs, maintaining a changelog, etc)
• Maybe add "Updating your saltext" section (updating the copier template, etc)

3. Extraction of Salt core modules

I tried the https://github.com/salt-extensions/extension_migration tool and found a couple of issues

• it expects the modules to be present in the repo, but they are not because the great purge PR is merged
• it uses some globbing to match the module names, and in theory that could result in false positives or negatives.

If nobody wants to improve that tool, I can describe the manual process I used to preserve the Git history for extracted modules (I already have the notes). It is a bit cumbersome though.

4. Great module migration (TODO)

If you intention was to put a little bit of historical context in this section, I can fill it in.

[max-arnold]

Also a little friction point with this repo itself (feel free to ignore):

• I cloned the PR locally to build/preview the docs
• Created a .venv inside of the repo
• Ran pip install -e . expecting that it will pull the right sphinx dependencies, but it failed horribly
• Had to manually run pip install nox (not sure what is the right version), nox -e docs --install-only, then make html (out of habit, it failed though), then finally nox -e docs
• Ran python -m http.server to access the docs outside of my development VM

[lkubb]

Thanks for taking a look!

Just some quick comments:

where this should live and how users will discover it

In the first iteration, I imagined this to live under this repository's GH page, i.e. salt-extensions.github.io/salt-extension-copier, but I'm open to better suggestions. The target audience is mostly devs though, which does not really fit in with the other (user/install) guides imho. I would also like this guide to be quick and easy to amend in the beginning, which makes me favor a repository inside this organization.

put a little bit of historical context in this section

Yes, some historic context + consequences (both benefits and drawbacks). I have the feeling many users don't know about the Great Module Migration and are stumped when they first discover it.

I'd also like to point out somewhere prominent that anyone who depends on specific modules should consider creating/maintaining the Salt extension. Not sure if people are aware they can make a difference here.

Also a little friction point with this repo itself

Yeah, pip install -e . will not work since this is not a Python package in itself. You'll just need nox installed (not sure about version constraints tbh). Then you can run nox -e docs-dev and you'll have an automatically updating rendering opened in your default browser. You don't need --install-only etc. It's only served on localhost though, so if you're rendering the docs on another system, you'll need to SSH tunnel 127.0.0.1:8000. I could make the listening IP configurable for this case though. I made it possible to override the host like this: nox -e docs-dev -- --host=1.2.3.4. When it's overridden, the browser is not launched automatically.

To build the docs once, just use nox -e docs.

Note: If you're on MacOS + Homebrew, you'll need to install enchant and - on Apple Silicon - prefix PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.2.dylib to these commands.

I would like to expand the structure a bit to reflect the whole lifecycle

👍 Agreed, just wanted to get the discussion going as soon as possible since the whole process is documented poorly + in a scattered fashion. We'll need a lot of outside contributions if we want to get anywhere. Feel free to create a PR against the branch this is based on if you find the time.

I tried the salt-extensions/extension_migration tool and found a couple of issues

Oh, didn't realize that. Could your method be used to fix the tool? I fear this could become a serious friction point for the migration otherwise.

[max-arnold]

This starts the http server twice for me - first when I run nox -e docs-dev -- --host 0.0.0.0, and second when I press Ctrl+C to stop it (it runs the cleanup task)

[lkubb]

Thanks for the feedback, this will improve the noxfile for all Salt extensions.

I removed the parametrization of docs-dev since it makes invocation cumbersome and I'm not completely sure what the point of it is.

[max-arnold]

I removed the parametrization of docs-dev since it makes invocation cumbersome and I'm not completely sure what the point of it is.

See saltstack/salt#58156

It seems to be not important, especially for extensions due to much smaller docs and build time.

[max-arnold]

Submitted a PR here lkubb#1

[max-arnold]

Added this doc link to the GH org profile salt-extensions/.github#1

[max-arnold]

I think the link to this guide should be added to the README.md in the base Copier template, so it is present in each extension. Another thing to consider is to make extension READMEs more DRY and just link to the relevant section(s) of the guide.

UPD: the extension README.md template has outdated instructions on how to preview the docs locally

[lkubb]

I'm merging this in now to get the docs out in some fashion, but still holding off on tagging a new template version in case you @max-arnold have suggestions for the updated README.

Thanks a lot for your continued involvement!

The new template version will contain several minor fixes and also make the rolling docs the default. It should happen before more migrations are performed.

Outstanding issues:

• We'll address Add docs #31 (comment) once there is an actionable solution.
• The guide mentions the repo request in Add repo request issue template community#15, which is not live yet.
• Still need to update this project's README to point to the documentation, there's no point in duplicating information.

I would prefer if the annoying boilerplate recreation during updates was fixed as well before actively inviting more people, but the required Copier PR is still in limbo.

[max-arnold]

The updated README looks perfect!