Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Moved generated module RSTs to their own directory. #33966

Merged
merged 4 commits into from
Dec 21, 2017
Merged

Moved generated module RSTs to their own directory. #33966

merged 4 commits into from
Dec 21, 2017

Conversation

dharmabumstead
Copy link
Contributor

SUMMARY

Moves generated module RSTs to their own subdirectory and updates index.html to point to the modules_by_category file.

ISSUE TYPE
  • Feature Pull Request
  • New Module Pull Request
  • Bugfix Pull Request
  • Docs Pull Request
COMPONENT NAME
ANSIBLE VERSION
ADDITIONAL INFORMATION

@ansibot ansibot added affects_2.5 This issue/PR affects Ansible v2.5 docs_pull_request needs_triage Needs a first human triage before being processed. support:core This issue/PR relates to code supported by the Ansible Engineering Team. labels Dec 16, 2017
gundalow
gundalow requested changes Dec 16, 2017
View reviewed changes
Copy link
Contributor

@gundalow gundalow left a comment •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will need some more work, as links from the main docs to any modules are broken, e.g.

/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/porting_guide_2.4.rst:85: WARNING: undefined label: win_msi (if the link has no caption the label must precede a section header)
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/porting_guide_2.4.rst:85: WARNING: undefined label: win_package (if the link has no caption the label must precede a section header)
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/porting_guide_2.4.rst:90: WARNING: undefined label: win_get_url (if the link has no caption the label must precede a section header)
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/porting_guide_2.4.rst:91: WARNING: undefined label: win_unzip (if the link has no caption the label must precede a section header)

Also make webdocs doesn't appear to generate html for any modules, nor list_of_network_$CATEGORY.html pages.

@gundalow gundalow removed the needs_triage Needs a first human triage before being processed. label Dec 16, 2017
@ansibot ansibot added the needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. label Dec 16, 2017
@dharmabumstead
Copy link
Contributor Author

Should’ve marked it WIP, since I knew I’d have to make another sweep for broken links.

I will check again, but when I tested this the module HTML and module list pages seemed to generate just fine doing local builds on my system.

@dharmabumstead
Copy link
Contributor Author

@gundalow Let's chat about this on slack Monday. I am getting the 'undefined label' warning on my local build as well, but the links in the local doc build are working.

@gundalow
Copy link
Contributor 

make webdocs
find docs/docsite/_build/ -name "*.html"  | wc -l
303

@gundalow gundalow changed the title Moved generated module RSTs to their own directory. [WIP] Moved generated module RSTs to their own directory. Dec 18, 2017
@gundalow gundalow added the WIP This issue/PR is a work in progress. Nevertheless it was shared for getting input from peers. label Dec 18, 2017
@gundalow
Copy link
Contributor

gundalow commented Dec 19, 2017 •
edited

  1. docs/docsite/Makefile
    Need to add rm -rf modules into the clean: block
    Should also keep the existing rm's 60-62 as in case people have files left from a previous make webdocs

  2. .gitignore
    needs to include
    docs/docsite/rst/modules/

@gundalow
Copy link
Contributor

  1. docs/bin/plugin_formatter.py
`t = _MODULE.sub(r':ref:`' + r"\1 <module_docs/\1>" + r"`", t)`

This will fix the U(lineinfile) links in DOCUMENTATION

Will need to carefully review make webdocs output to check for any other broken links

@dharmabumstead dharmabumstead changed the title [WIP] Moved generated module RSTs to their own directory. Moved generated module RSTs to their own directory. Dec 20, 2017
@ansibot ansibot removed the WIP This issue/PR is a work in progress. Nevertheless it was shared for getting input from peers. label Dec 20, 2017
@bcoca
Copy link
Member

bcoca commented Dec 20, 2017

do you want them all 'flat' in module_docs/ or do you want them by category/subcat also?

@dharmabumstead
Copy link
Contributor Author

@bcoca: That'd be OK with me at some point, but for simplicity's sake I'd prefer to leave them flat in the module_docs directory for for now. I just want them out of the root RST directory so I can proceed with the rest of the reorg.

@gundalow
Copy link
Contributor

  1. Will need rewrite rules on docs.ansible.com, though only for 2.5 and on wards
    http://docs.ansible.com/ansible/devel/command_module.html ->
    http://docs.ansible.com/ansible/devel/module_docs/command_module.html

Most of these warnings are caused by this PR

/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/dev_guide/developing_modules_documenting.rst:191: WARNING: unknown document: ../list_of_all_modules
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst:25: WARNING: unknown document: ../list_of_all_modules
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst:29: WARNING: unknown document: dev_guide/testing
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst:29: WARNING: unknown document: ../list_of_network_modules
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst:36: WARNING: unknown document: ../list_of_database_modules
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst:40: WARNING: unknown document: ../list_of_all_modules
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/dev_guide/testing_units.rst:191: WARNING: unknown document: testing_units_running_locally
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/module_docs/win_dsc_module.rst:24: WARNING: unknown document: windows_dsc
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/modules_support.rst:11: WARNING: unknown document: core_maintained
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/modules_support.rst:17: WARNING: unknown document: network_maintained
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/modules_support.rst:17: WARNING: unknown document: list_of_network_modules
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/modules_support.rst:28: WARNING: unknown document: community_maintained
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/playbooks_loops.rst:90: WARNING: unknown document: Jinja2 lookups playbooks_lookups
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/playbooks_loops.rst:90: WARNING: unknown document: filters playbooks_filters
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/playbooks_loops.rst:90: WARNING: unknown document: tests playbooks_tests
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/plugins/callback.rst:16: WARNING: unknown document: mail callback/mail
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/plugins/callback.rst:19: WARNING: unknown document: callback/oxs_say
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/plugins/connection.rst:47: WARNING: unknown document: connection/paramiko
/home/johnb/git/ansible-inc/tmp/dharmabumstead-module-build-move-1/docs/docsite/rst/plugins/lookup.rst:39: WARNING: unknown document: ../template_module
  1. Will need rewrite rules adding for some/most of (2), especially core_maintained ,etc which I believe external sites link to.

Is this really worth all the effort, what's the problem we are trying to solve? If it's files in the way, doesn't make clean solve that?

@dharmabumstead
Copy link
Contributor Author

dharmabumstead commented Dec 20, 2017 •
edited

Yes, it's worth the effort; that's why we're doing this. Yes, there are some links that will need fixing.

Unless anyone has an absolute showstopper/build break, I plan on merging this by tomorrow.

@gundalow
Copy link
Contributor

Fine as long as the old module URLs continue to work, so the rewrite rules will need adding as soon as this is live.

shipit

@ansibot ansibot removed the needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. label Dec 21, 2017
@dharmabumstead dharmabumstead merged commit f8f34c7 into ansible:devel Dec 21, 2017
@ansibot ansibot added docs This issue/PR relates to or includes documentation. feature This issue/PR relates to a feature request. and removed docs_pull_request labels Mar 4, 2018
@ansible ansible locked and limited conversation to collaborators Apr 26, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@gundalow gundalow gundalow requested changes

@alikins alikins Awaiting requested review from alikins

@bcoca bcoca Awaiting requested review from bcoca

Assignees
No one assigned
Labels
affects_2.5 This issue/PR affects Ansible v2.5 docs This issue/PR relates to or includes documentation. feature This issue/PR relates to a feature request. support:core This issue/PR relates to code supported by the Ansible Engineering Team.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
4 participants
@dharmabumstead @gundalow @bcoca @ansibot