Add docs for the filter reveal_ansible_type and the test ansible_type. #8645

vbotka · 2024-07-16T05:42:39Z

SUMMARY

Add below files to docs/docsite/rst:

filter_guide-abstract_informations-types.rst
filter_guide-abstract_informations-types-reveal_ansible_type.rst

Update the below files in docs/docsite/rst:

filter_guide_abstract_informations.rst
test_guide.rst

ISSUE TYPE

Docs Pull Request

COMPONENT NAME

ADDITIONAL INFORMATION

ansibullbot · 2024-07-16T06:02:44Z

cc @felixfontein
click here for bot help

vbotka · 2024-07-16T07:00:53Z

@russoz, quoting your comment from #8595:

well, personally I still think the test code is more verbose than it needs to be, but I am happy to have it as-is, and we may review it later if needed.

How would you like to change the test code?

russoz

Hi @vbotka thanks for your contribution! It does look like you imagined a dynamic way to generate documentations within the repository, and that is not something we would like to do. There are processes that read (and expect) .rst files only within that directory.
Moreover, it looks like there are parts of a test for your plugins and tests based in Ansible YAML, as opposed to unit testing python code, should be placed in the tests/integration/targets// directory.
This PR is quite irregular and not in conformance with our practices.
Please review the documentation (a good starting point being: https://github.com/ansible-collections/community.general/blob/main/CONTRIBUTING.md) and see how other documentation was written.

russoz · 2024-07-16T11:11:20Z

docs/docsite/rst/test_guide.rst

This removes existing documentation for existing plugins.

I restored the origin and added new section.

russoz · 2024-07-16T11:17:07Z

docs/docsite/helper/ansible_type/playbook.yml

This is out of place. There are scripts and processes that work with the documentation files that will not execute playbooks in this context.

russoz · 2024-07-16T11:18:42Z

docs/docsite/helper/reveal_ansible_type/templates/tasks.yml.j2

Tests "roles" should be place in the tests/integration/target directory, not here.

russoz · 2024-07-16T11:41:53Z

@russoz, quoting your comment from #8595:

well, personally I still think the test code is more verbose than it needs to be, but I am happy to have it as-is, and we may review it later if needed.

How would you like to change the test code?

Well, that was then. I have not spent more time on the PR after that commenting. TBH, I will not have much time in the upcoming days. And that question seems to be a bit out of context in this PR.
You are the maintainer of that code, if I make any suggestions in the future you will receive notifications for them.

vbotka · 2024-07-16T12:20:48Z

This PR is quite irregular and not in conformance with our practices.

Hi @russoz. Thank you for the review!

There are only docs/docsite/rst/*.rst files and BOTMETA.yml changes left. This should be in conformance now.

.github/BOTMETA.yml
docs/docsite/rst/filter_guide-abstract_informations-types-reveal_ansible_type.rst
docs/docsite/rst/filter_guide-abstract_informations-types.rst
docs/docsite/rst/filter_guide_abstract_informations.rst
docs/docsite/rst/test_guide.rst

vbotka · 2024-07-16T13:17:32Z

@russoz, would it be possible to review also ##8647? This removes other helpers I created in the past. Sorry for the noise.

felixfontein · 2024-07-16T21:18:48Z

Hi @vbotka thanks for your contribution! It does look like you imagined a dynamic way to generate documentations within the repository, and that is not something we would like to do.

Why not? I think it's a good idea to generate example outputs in documentation using the actual code, if possible.

(It would be great if there would be a more generic way to do this instead of having to do so much templating, but right now there isn't. There used to be https://github.com/ansible-community/sphinx-ansible, but that's dead, and wouldn't have worked here anyway since the RST files are consumed by Sphinx without that extension.)

Moreover, it looks like there are parts of a test for your plugins and tests based in Ansible YAML, as opposed to unit testing python code, should be placed in the tests/integration/targets// directory.

I agree that testing should not be mixed up with documentation generation. (I already mentioned that in this thread: #8482 (comment))

felixfontein · 2024-07-21T20:48:38Z

.github/BOTMETA.yml

@@ -1460,6 +1460,10 @@ files:
    maintainers: vbotka
  docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst:
    maintainers: vbotka
+  docs/docsite/rst/filter_guide-abstract_informations-types.rst:


Please use underscores:

Suggested change

docs/docsite/rst/filter_guide-abstract_informations-types.rst:

docs/docsite/rst/filter_guide-abstract_informations_types.rst:

Same below.

Why is this needed?

The name of the file is a concatenation of three headings' levels:

filter_guide

abstract_informations

type

The concatenation by dash "-" keeps this information. I've already created a couple of files this way. Should all of them be renamed?

You kept the first dash. Do you think this one should be replaced too?

For the record: This name is used in filter_guide_abstract_informations.rst

I didn't catch the dashes in the previous PR. Generally all filenames in docs/docsite/rst/ use underscores instead of dashes. It would be great to keep it that way.

felixfontein · 2024-07-21T20:49:36Z

docs/docsite/rst/filter_guide-abstract_informations-types.rst

+Types
+^^^^^
+
+Filters to manage Ansible types


Suggested change

Filters to manage Ansible types

Filters to manage Ansible types.

felixfontein · 2024-07-21T20:52:56Z

docs/docsite/rst/filter_guide-abstract_informations-types-reveal_ansible_type.rst

+
+.. versionadded:: 9.2.0
+
+**Substitution converts str to AnsibleUnicode**


This is a heading, so it should be a heading and not a paragraph with manual formatting applied:

Suggested change

**Substitution converts str to AnsibleUnicode**

Substitution converts str to AnsibleUnicode

-------------------------------------------

Similar below.

This would violate the heading levels:

community.general Filter Guide ============================== Abstract transformations ------------------------ Types ^^^^^ Filter reveal_ansible_type """"""""""""""""""""""""""

I'm afraid there are no more levels left.

RST allows quite a few different levels. You can use ~~~~~~~~ or ..... or ****** or +++++++ or ... then :)

felixfontein · 2024-07-21T20:53:27Z

docs/docsite/rst/filter_guide-abstract_informations-types-reveal_ansible_type.rst

+
+**Substitution converts str to AnsibleUnicode**
+
+* String. AnsibleUnicode.


What does this mean? (I know what it means, but regular users do not.)

I'll improve all the comments.

vbotka added 2 commits July 16, 2024 07:11

Add docs for the filter reveal_ansible_type and the test ansible_type.

eeee05f

Add BOTMETA entries.

08a2f8e

ansibullbot added the docs label Jul 16, 2024

russoz requested changes Jul 16, 2024

View reviewed changes

ansibullbot added the needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR label Jul 16, 2024

Helpers removed.

45885da

Do not remove existing documentation for existing plugins.

594b732

vbotka requested a review from russoz July 16, 2024 12:43

vbotka mentioned this pull request Jul 16, 2024

Docs. Remove helpers. #8647

Open

felixfontein added check-before-release PR will be looked at again shortly before release and merged if possible. backport-9 Automatically create a backport for the stable-9 branch labels Jul 16, 2024

felixfontein reviewed Jul 21, 2024

View reviewed changes

ansibullbot added stale_ci CI is older than 7 days, rerun before merging stale_review labels Jul 31, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs for the filter reveal_ansible_type and the test ansible_type. #8645

Add docs for the filter reveal_ansible_type and the test ansible_type. #8645

vbotka commented Jul 16, 2024 •

edited

Loading

ansibullbot commented Jul 16, 2024

vbotka commented Jul 16, 2024

russoz left a comment •

edited

Loading

russoz Jul 16, 2024

vbotka Jul 16, 2024

russoz Jul 16, 2024

vbotka Jul 16, 2024

russoz Jul 16, 2024

vbotka Jul 16, 2024

russoz commented Jul 16, 2024

vbotka commented Jul 16, 2024 •

edited

Loading

vbotka commented Jul 16, 2024

felixfontein commented Jul 16, 2024

felixfontein Jul 21, 2024

vbotka Jul 21, 2024

felixfontein Jul 23, 2024

felixfontein Jul 21, 2024

felixfontein Jul 21, 2024

vbotka Jul 21, 2024

felixfontein Jul 23, 2024

felixfontein Jul 21, 2024

vbotka Jul 21, 2024

	Filters to manage Ansible types
	Filters to manage Ansible types.


		.. versionadded:: 9.2.0

		Substitution converts str to AnsibleUnicode

	Substitution converts str to AnsibleUnicode
	Substitution converts str to AnsibleUnicode
	-------------------------------------------


		Substitution converts str to AnsibleUnicode

		* String. AnsibleUnicode.

Add docs for the filter reveal_ansible_type and the test ansible_type. #8645

Are you sure you want to change the base?

Add docs for the filter reveal_ansible_type and the test ansible_type. #8645

Conversation

vbotka commented Jul 16, 2024 • edited Loading

SUMMARY

ISSUE TYPE

COMPONENT NAME

ADDITIONAL INFORMATION

ansibullbot commented Jul 16, 2024

vbotka commented Jul 16, 2024

russoz left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

russoz commented Jul 16, 2024

vbotka commented Jul 16, 2024 • edited Loading

vbotka commented Jul 16, 2024

felixfontein commented Jul 16, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vbotka commented Jul 16, 2024 •

edited

Loading

russoz left a comment •

edited

Loading

vbotka commented Jul 16, 2024 •

edited

Loading