Enable sitemap creation for the user guide

[scriptautomate-bc]

We should be generating a sitemap listing for the Sphinx-generated website.
Once this is in place, a sitemap listing should also be created for the salt baseline repo itself that points to each of the sitemaps of:

• salt install guide
• salt user guide
• salt ref docs

[scriptautomate-bc]

Related:

• Enable sitemap creation for the install guide salt-install-guide#30

[scriptautomate-bc]

@lumenCodes
This repo doesn't change much, and can iterate faster than trying to start with the other repos. It's small enough that it's easier to experiment with and test that things are functional.

Details that should be helpful:

• Sitemap extension: https://sphinx-sitemap.readthedocs.io/en/latest/getting-started.html
• html_baseurl would be: https://docs.saltproject.io/salt/user-guide/en/latest/
• I can't see any of the advanced features being useful except for Excluding Pages like search maybe?

If you run into any issues, such as contributing setup, etc. feel free to post in this thread. We could update the contributing info as we go, and I could prob bootstrap the repo with a devcontainer. We could look at the Salt Install Guide devcontainer as a base reference that could be updated if that would be most helpful.

After this is implemented, we can look into trying to figure out how to include the last modified sitemap standard based on git timestamps in a follow-up issue.

[lumenCodes]

Sure 🙂

I will read up on the sitemap extension. I will be sure to let you know if I have any issues. I will share an update on this in the next few hours.

Thank you @scriptautomate-bc

[lumenCodes]

Hello @scriptautomate-bc the first blocker I have is that I cannot find the link to the contribution guide. The existing links https://github.com/saltstack/salt-user-guide/blob/main/CONTRIBUTING.md and https://saltstack.gitlab.io/open/docs/docs-hub/topics/contributing.html is showing a 404 page.

Please can you point me to the guide.

[lumenCodes]

I think I found it. https://docs.saltproject.io/en/master/topics/development/contributing.html

Kindly confirm this is it.

[scriptautomate-bc]

Hello @scriptautomate-bc the first blocker I have is that I cannot find the link to the contribution guide. The existing links https://github.com/saltstack/salt-user-guide/blob/main/CONTRIBUTING.md and https://saltstack.gitlab.io/open/docs/docs-hub/topics/contributing.html is showing a 404 page.

Please can you point me to the guide.

Thanks for pointing this out.

This is pretty out-dated. I've done a quick review of the old guide for docs contrib, and have a WIP here you can reference while contributing now:

• https://gist.github.com/scriptautomate-bc/9139d3b305bdf6c8e9c50f8506f3d5c9

This should help unblock you 😎

[lumenCodes]

Thank you so much. This is really helpful. I am done with the setup.

I will make the changes later today.

[lumenCodes]

Hello @scriptautomate-bc the first blocker I have is that I cannot find the link to the contribution guide. The existing links https://github.com/saltstack/salt-user-guide/blob/main/CONTRIBUTING.md and https://saltstack.gitlab.io/open/docs/docs-hub/topics/contributing.html is showing a 404 page.
Please can you point me to the guide.

Thanks for pointing this out.

This is pretty out-dated. I've done a quick review of the old guide for docs contrib, and have a WIP here you can reference while contributing now:

• https://gist.github.com/scriptautomate-bc/9139d3b305bdf6c8e9c50f8506f3d5c9

This should help unblock you 😎

Hello @scriptautomate-bc

I have made the updates, however I could not build locally. I am getting this error Could not import extension sphinx_substitution_extensionssphinx_sitemap (exception: No module named 'sphinx_substitution_extensionssphinx_sitemap')

I want to install the extension using pip install sphinx_substitution_extensions . I just want to confirm I am not missing any step before I run the command.

[scriptautomate-bc]

I have made the updates, however I could not build locally. I am getting this error Could not import extension sphinx_substitution_extensionssphinx_sitemap (exception: No module named 'sphinx_substitution_extensionssphinx_sitemap')

I want to install the extension using pip install sphinx_substitution_extensions . I just want to confirm I am not missing any step before I run the command.

Your error makes it look like you have updated the conf.py file incorrectly, but I don't know what your change to that file looks like. You shouldn't have 'sphinx_substitution_extensionssphinx_sitemap' as a single line. You should be adding an extension as a separate entry.

You need to provide exactly what steps you've done so far, what modifications to what files, what pip commands you have ran, etc. for assistance. It may also be helpful to open a draft PR to this repo in order for me and others to see what files you have edited.

It would helpful to also follow something like StackOverflow's How do I ask a good question?, such as:

---

Help others reproduce the problem

Not all questions benefit from including code, but if your problem is with code you've written, you should include some. But don't just copy in your entire program! Not only is this likely to get you in trouble if you're posting your employer's code, it likely includes a lot of irrelevant details that readers will need to ignore when trying to reproduce the problem. Here are some guidelines:

• Include just enough code to allow others to reproduce the problem. For help with this, read How to create a Minimal, Reproducible Example.
• DO NOT post images of code, data, error messages, etc.—copy or type the text into the question. Please reserve the use of images for diagrams or demonstrating rendering bugs, things that are impossible to describe accurately via text. For more information please see the Meta FAQ entry Why not upload images of code/errors when asking a question?

[lumenCodes]

I have made the updates, however I could not build locally. I am getting this error Could not import extension sphinx_substitution_extensionssphinx_sitemap (exception: No module named 'sphinx_substitution_extensionssphinx_sitemap')
I want to install the extension using pip install sphinx_substitution_extensions . I just want to confirm I am not missing any step before I run the command.

Your error makes it look like you have updated the conf.py file incorrectly, but I don't know what your change to that file looks like. You shouldn't have 'sphinx_substitution_extensionssphinx_sitemap' as a single line. You should be adding an extension as a separate entry.

You need to provide exactly what steps you've done so far, what modifications to what files, what pip commands you have ran, etc. for assistance. It may also be helpful to open a draft PR to this repo in order for me and others to see what files you have edited.

It would helpful to also follow something like StackOverflow's How do I ask a good question?, such as:

Help others reproduce the problem

Not all questions benefit from including code, but if your problem is with code you've written, you should include some. But don't just copy in your entire program! Not only is this likely to get you in trouble if you're posting your employer's code, it likely includes a lot of irrelevant details that readers will need to ignore when trying to reproduce the problem. Here are some guidelines:

• Include just enough code to allow others to reproduce the problem. For help with this, read How to create a Minimal, Reproducible Example.
• DO NOT post images of code, data, error messages, etc.—copy or type the text into the question. Please reserve the use of images for diagrams or demonstrating rendering bugs, things that are impossible to describe accurately via text. For more information please see the Meta FAQ entry Why not upload images of code/errors when asking a question?

Thank you for your prompt response.

Yes I have fixed a part of the error. The error I am getting now is that the sitemap extensions is not installed properly.

So what have I done?

• I followed the setup process in the WIP contributing guide using the fork and branch method

• After the setup, I opened the conf.py file

• In the extensions array I added "sitemap-sphinx" and also added html_baseurl outside of the array

• I then activated the .venv and the nox -e docs as seen in the contribution guide

• The build did not complete and I am getting the error - could not import sphinx sitemap.

• I have confirmed that I added the sphinx sitemap correctly to the extensions array

• I would love to create a draft PR however the error is not allowing the tests to complete hence the commit is always aborted.

• I tried running the setup again to install dependencies and I got a message - already satisfied.

I don't know what else to do

[scriptautomate-bc]

Yes I have fixed a part of the error. The error I am getting now is that the sitemap extensions is not installed properly.

• nox references the docs/requirements.txt file for Python pip package installs. Have you added the extension to that requirements file?
• Instead of paraphrasing errors you run into, can you copy/paste the exact error message in the future? This is more helpful.

I would love to create a draft PR however the error is not allowing the tests to complete hence the commit is always aborted.

• If wanting to temporarily skip pre-commit locally (if that is blocking you), you can make sure to add --no-verify to your git commit command. This should allow you to commit what you are working on, and be able to push to your fork for creating a draft PR.

[lumenCodes]

Thank you for the feedback.

Instead of paraphrasing errors you run into, can you copy/paste the exact error message in the future? This is more helpful.

The exact error is
File "C:\Users\USER\Desktop\Open Source\Salt\salt-user-guide\.nox\docs\Lib\site-packages\sphinx\registry.py", line 544, in load_extension raise ExtensionError( __('Could not import extension %s') % extname, err ) from err sphinx.errors.ExtensionError: Could not import extension sphinx-sitemap (exception: No module named 'sphinx-sitemap')

nox references the docs/requirements.txt file for Python pip package installs. Have you added the extension to that requirements file?

I did not make any update to requirements file. I just ran the following commands to install the requirements pip install -U pip setuptools wheel and pip install -r requirements-dev.txt

I have also created a draft PR.

[scriptautomate-bc]

I did not make any update to requirements file. I just ran the following commands to install the requirements pip install -U pip setuptools wheel and pip install -r requirements-dev.txt

You need to update the requirements file so that nox knows about the new sitemap extension you are trying to use, otherwise the extension is not installed for testing.

[lumenCodes]

I have updated the requirements.txt file with the name of the extension, I am still getting the same error. I have also pushed the commit to the draft PR.

[scriptautomate-bc]

I have updated the requirements.txt file with the name of the extension, I am still getting the same error. I have also pushed the commit to the draft PR.

k, moving discussion to the PR:

• Adding the Sphinx sitemap #2

[scriptautomate-bc]

@lumenCodes Thanks for completing your first issue for Salt Project! 🥳

The following PRs made all the necessary changes for initial sitemap configuration in this repo:

• Adding the Sphinx sitemap #2
• Cleanup tech debt, optimize devcontainer, and fix sitemap URL generation #5
• Exclude some initial files from sitemap #7

This has now resulted in the following published file:

• https://docs.saltproject.io/salt/user-guide/en/latest/sitemap.xml

Very similar application of updates should now be capable of being applied to the Salt Install Guide in the following issue, if you'd like to continue helping out with introducing sitemaps:

• Enable sitemap creation for the install guide salt-install-guide#30