Document Windows App Control Feature

[jborean93]

This adds some documentation for a new feature added in Ansible 2.19.

[jborean93]

This is quite a large script so a literalinclude may not be the best idea. Any suggestions on how to potentially just link to the script this points to instead as a hyperlink?

[samccann]

@oraNod might have better ideas but see this line for how we did it in the past in the network getting started guide.

[oraNod]

The :download: directive that @samccann mentions is a good option. Although maybe it's not that informative and forces the reader to download a script and then go away from the docs and get off track.

You could do kind of a hybrid approach like this where you just include a portion of the script:

.. literalinclude:: powershell/New-AnsiblePowerShellSignature.ps1
   :lines: 11-21
   
You can view the complete script at `New-AnsiblePowerShellSignature.ps1 <path/to/powershell/New-AnsiblePowerShellSignature.ps1>`_.

Another approach could be creating a codeblock that highlights excerpts from the script and adds some comments. Although looking at the script it's well documented with examples so it might be hard to squeeze all of that into a codeblock. If it would be possible to give a really concise overview (maybe the Signs just the content include in Ansible and the ansible.windows collection example?) to give the reader a sense of how to use the script then follow the codeblock with either the download directive or a hyperlink.

[jborean93]

That sounds like a good approach, I'll try them out and see how it looks.

[jborean93]

I ended up going with a simple hyperlink, people can open it in a new tab to view the source or download without having it automatically download.

[oraNod]

@jborean93 That sounds like a good approach but the link seems to be broken. Looking at the preview build here: https://ansible--2654.org.readthedocs.build/projects/ansible-core/2654/os_guide/windows_app_control.html

[jborean93]

Looks like I was missing the trailing _, not sure if I need to do anything extra to ensure the os_guide/powershell/* contents are present in the build directory.

[oraNod]

@jborean93 I think the way to achieve that is either with html_extra_path or html_static_path in conf.py. See here: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path

I've tried html_extra_path but the directory structure in the build doesn't match the link url that gets generated.

Maybe we add it to the examples directory and link to the GitHub url?

[jborean93]

I originally had this as .. code-block:: xml to get some XML highlighting but it seems like we don't have it enabled/allowed in this repo. Happy with text here but if we want to enable xml I can always change this back.

[samccann]

hey I'm not sure how do enable xml?

[Akasurde]

jFYI, https://github.com/ansible-community/ansible-pygments is used as a custom pygments in ansible doc, this is specified in conf.py by pygments = 'ansible'

[jborean93]

The failing message was at https://github.com/ansible/ansible-documentation/actions/runs/15195285949/job/42737710900

/home/runner/work/ansible-documentation/ansible-documentation/docs/docsite/rst/os_guide/windows_app_control.rst:31:4: Warning: literal block with disallowed language: xml. If the language should be allowed, the checker needs to be updated. Currently allowed languages are: ansible-output, bash, console, csharp, diff, ini, jinja, json, md, none, powershell, python, rst, sh, shell, shell-session, text.

We have some documentation on this at https://github.com/ansible/ansible-documentation/blob/510375f072a8dce15a389ced9888dda93975b29d/docs/docsite/rst/dev_guide/style_guide/index.rst#syntax-highlighting---pygments and the list/check is coded at

ansible-documentation/tests/checkers/rst-yamllint.py

Lines 26 to 44 in 510375f

	ALLOWED_LANGUAGES = {
	"ansible-output",
	"bash",
	"console",
	"csharp",
	"diff",
	"ini",
	"jinja",
	"json",
	"md",
	"none",
	"powershell",
	"python",
	"rst",
	"sh",
	"shell",
	"shell-session",
	"text",
	}

.

I'm not sure if it's just us simply adding xml to this list so the check doesn't fail or whether there are other things that need to be enabled in the build to get it working.

[Akasurde]

Maybe?

Suggested change

	.. code-block:: text
	.. code-block:: XML

[jborean93]

Unfortunately the xml highlighting needs to be enabled in the project first.

[samccann]

@oraNod PTAL

[oraNod]

IMO this shouldn't be a warning. Notes of type warning should be reserved for something that will cause data loss, system damage, or some other kind of breakage. We should use warnings sparingly so that they are more obvious to users.

How about using the admonition directive like this?

.. admonition:: Experimental functionality

I would also change "tech preview" to "experimental functionality" because tech preview is more of a Red Hat term and probably best avoided in community docs. If there's some reason to use tech preview though, it's fine. It's just semantics and the point still comes across either way.

[jborean93]

Updated with the changes here.