Unit test to require execution module documentation #52368

mchugh19 · 2019-03-30T22:41:31Z

What does this PR do?

Adds unit test to validate that salt module, state, returners, wheel, etc files have a matching rst in docs and checks that doc rst files have matching py.
Also adds missing docs so that the tests pass

Previous Behavior

Modules could be added without documentation link

New Behavior

Unit test will catch that modules do not have associated docs

python tests\runtests.py -n unit.test_doc.DocTestCase.test_states_doc_files

AssertionError: 'zabbix_usermacro' not found in ['acme', 'alias', '...
'zone', 'zookeeper', 'zpool'] : State file zabbix_usermacro is missing documentation in ...salt/doc/ref/states/all

Tests written?

Yes

Commits signed with GPG?

No

waynew

Nice! I ❤️ better docs!

waynew · 2019-04-02T15:38:07Z

02:09:36 /var/jenkins/workspace/pr-doc_PR-52368-YBQWFDKYTXAEE66QNONYBROXKZYDY3U4XQ4FDLNWAOWZLXEJGTKA/salt/states/azurearm_dns.py:docstring of salt.states.azurearm_dns:22:Field list ends without a blank line; unexpected unindent.
02:09:36 make: *** [html] Error 2
02:09:36 make: Leaving directory `/var/jenkins/workspace/pr-doc_PR-52368-YBQWFDKYTXAEE66QNONYBROXKZYDY3U4XQ4FDLNWAOWZLXEJGTKA/doc'```

waynew

Looks like the doc build failed

mchugh19 · 2019-04-02T16:48:11Z

Yep. Since the test finds missing docs, I then added lots of missing rst files. Because they've never been used, it turns out there are many typos and errors that Sphinx chokes on. I've then started going through those errors and I'm now up to working through the state errors. So it will probably be another couple of days until I can get everything building again.

While needed it's turned out to be a suckier project than first expected. But I now know a bit more about rst syntax than I did before 😋

Relatedly, once it works, we'll want to get this merged quickly as it has required touching lots of module files to fix their documentation. Letting it linger risks constant merge conflicts.

waynew · 2019-04-02T17:36:31Z

That makes sense :)

Ping me when it's (re)-ready to merge and I'll make sure to get it shepherded 🐑 🚀 😀

mchugh19 · 2019-04-03T07:15:34Z

Down to the last doc error of:

Warning, treated as error:
<autosummary>:1:Unknown target name: "aws kms envelope encryption".

Edit: looks like it's from aws_kms renderer. Taking a look...

Any thoughts? Otherwise this looks good to go!

Pshew!

mchugh19 · 2019-04-04T06:30:24Z

I think we've got a clean build!

The unit test only checks that each python file has a corresponding rst file. The doc build process errors if the rst file isn't referenced, forcing the human to add the entry to an index file, but it doesn't clearly state that process. Not sure how often that comes up, but in PRs it should be discovered.

Anyway, I think this is all set to go. @waynew care to look it over once more with the team and merge?

mchugh19

build is now clean

changes 👍

mchugh19 · 2019-04-15T21:43:10Z

ping @waynew. This should go in before too many conflicting files are updated.

waynew · 2019-04-17T14:08:03Z

Hey @mchugh19 It appears that something is wonky with the PR builds. Specifically, they're failing before the tests even start. Could you try rebasing? If that doesn't clear up the tests then we may want to try just opening a new PR, but 🤞

mchugh19 · 2019-04-17T16:04:05Z

Can do, but I'm away on holiday for the next couple of weeks. If anyone wants to give it a go, please do. Otherwise I'll be back around the start of May.

…

On Wed, Apr 17, 2019, 16:08 Wayne Werner ***@***.***> wrote: Hey @mchugh19 <https://github.com/mchugh19> It appears that something is wonky with the PR builds. Specifically, they're failing before the tests even start. Could you try rebasing? If that doesn't clear up the tests then we may want to try just opening a new PR, but 🤞 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#52368 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABTB5QEVxagfnLb1xE-SoBQfEKEVIOyJks5vhyrhgaJpZM4cUAYY> .

waynew · 2019-05-23T14:29:59Z

Pretty sure these other failures are also unrelated - re-running now (they look like they failed in the setup step)

mchugh19 · 2019-05-28T15:44:41Z

Can we get this backported to earlier releases? Docs should probably be accurate for supported releases.

Ch3LL · 2019-05-31T21:11:05Z

of course! I'll add the backport label and it will get backported when its merged.

Correct spacing

Ch3LL · 2019-06-06T19:26:27Z

thanks for this one @mchugh19 ! This will be great to have. I'll try backporting it tomorrow or monday :)

Unit test to require execution module documentation

Port #52368 doc requirement tests to master

mchugh19 requested a review from a team as a code owner April 2, 2019 07:05

waynew approved these changes Apr 2, 2019

View reviewed changes

waynew previously requested changes Apr 2, 2019

View reviewed changes

mchugh19 commented Apr 5, 2019

View reviewed changes

max-arnold mentioned this pull request May 1, 2019

Conformance tests #52775

Open

mchugh19 added 16 commits May 8, 2019 16:59

initial tests for module documentation

9078210

add aixpkg docs

0d480d3

add aix_shadow

5147505

add aptly doc

5ba8dc5

add azurearm_dns docs

4d0d993

add baredoc docs

5a5b13d

add boto3_sns docs

1b96909

add boto_s3 docs

bc1068c

add boto_ssm docs

da69c20

add chroot docs

aa3f32d

add needed modules for doc test

d4c5e4f

add state documention tests and missing docs

62ccbeb

update formatting

0fbd9f2

Update salt.modules.aixpkg.rst

099ea8d

Update salt.modules.aptly.rst

c0d2d31

Update salt.modules.azurearm_dns.rst

507f33e

KChandrashekhar added the ZRELEASED - Neon retired label label May 22, 2019

Merge branch 'develop' into doc_tests

3262b87

This was referenced May 27, 2019

Add autodoc for the Docker proxy module #53250

Closed

2018.3 missing mod docs #53253

Closed

Adding autodoc for the several proxy modules #53247

Closed

Azure: Add autodoc files for azurearm_dns modules #53239

Closed

Merge branch 'develop' into doc_tests

cd13e55

Ch3LL added the bugfix-bckport will be be back-ported to an older release branch by creating a PR against that branch label May 31, 2019

Update baredoc.py

5188831

Correct spacing

mchugh19 mentioned this pull request Jun 1, 2019

Add autodoc for the VMWare proxy modules #53249

Closed

Merge branch 'develop' into doc_tests

6189d64

mchugh19 mentioned this pull request Jun 4, 2019

Added refs to AIX module documentation #53369

Merged

waynew approved these changes Jun 5, 2019

View reviewed changes

Ch3LL added the Awesome label Jun 6, 2019

garethgreenaway approved these changes Jun 6, 2019

View reviewed changes

Ch3LL approved these changes Jun 6, 2019

View reviewed changes

Ch3LL merged commit 124c8ec into saltstack:develop Jun 6, 2019

Ch3LL mentioned this pull request Jun 11, 2019

Backport #52368 into 2018.3 #53456

Closed

Ch3LL added ZZZ[Done]-back-ported-bf RETIRED The pull request has been back-ported to an older branch. and removed bugfix-bckport will be be back-ported to an older release branch by creating a PR against that branch labels Jun 11, 2019

mchugh19 deleted the doc_tests branch July 4, 2019 14:22

mchugh19 pushed a commit to mchugh19/salt that referenced this pull request Jan 19, 2020

Merge pull request saltstack#52368 from mchugh19/doc_tests

d8b505e

Unit test to require execution module documentation

mchugh19 mentioned this pull request Jan 19, 2020

Port #52368 doc requirement tests to master #55914

Merged

dwoz added a commit that referenced this pull request Apr 14, 2020

Merge pull request #55914 from mchugh19/doctest_master

fed72cb

Port #52368 doc requirement tests to master

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Unit test to require execution module documentation #52368

Unit test to require execution module documentation #52368

mchugh19 commented Mar 30, 2019 •

edited

Loading

waynew left a comment

waynew commented Apr 2, 2019

waynew left a comment

mchugh19 commented Apr 2, 2019 •

edited

Loading

waynew commented Apr 2, 2019

mchugh19 commented Apr 3, 2019 •

edited

Loading

mchugh19 commented Apr 4, 2019

mchugh19 left a comment

mchugh19 commented Apr 15, 2019

waynew commented Apr 17, 2019

mchugh19 commented Apr 17, 2019 via email

waynew commented May 23, 2019

mchugh19 commented May 28, 2019

Ch3LL commented May 31, 2019

Ch3LL commented Jun 6, 2019 •

edited

Loading

Unit test to require execution module documentation #52368

Unit test to require execution module documentation #52368

Conversation

mchugh19 commented Mar 30, 2019 • edited Loading

What does this PR do?

Previous Behavior

New Behavior

Tests written?

Commits signed with GPG?

waynew left a comment

Choose a reason for hiding this comment

waynew commented Apr 2, 2019

waynew left a comment

Choose a reason for hiding this comment

mchugh19 commented Apr 2, 2019 • edited Loading

waynew commented Apr 2, 2019

mchugh19 commented Apr 3, 2019 • edited Loading

mchugh19 commented Apr 4, 2019

mchugh19 left a comment

Choose a reason for hiding this comment

mchugh19 commented Apr 15, 2019

waynew commented Apr 17, 2019

mchugh19 commented Apr 17, 2019 via email

waynew commented May 23, 2019

mchugh19 commented May 28, 2019

Ch3LL commented May 31, 2019

Ch3LL commented Jun 6, 2019 • edited Loading

mchugh19 commented Mar 30, 2019 •

edited

Loading

mchugh19 commented Apr 2, 2019 •

edited

Loading

mchugh19 commented Apr 3, 2019 •

edited

Loading

Ch3LL commented Jun 6, 2019 •

edited

Loading