[WIP] Adding docs #5
Conversation
abadger
force-pushed
the
adding-docs
branch
4 times, most recently
from
f69509d to
a3cff46
Compare
|
This pull request introduces 5 alerts when merging a3cff46 into fa46cb7 - view on LGTM.com new alerts:
|
Codecov Report
@@ Coverage Diff @@
## master #5 +/- ##
===========================================
+ Coverage 3.76% 15.25% +11.48%
===========================================
Files 17 5 -12
Lines 1646 400 -1246
Branches 318 43 -275
===========================================
- Hits 62 61 -1
+ Misses 1580 335 -1245
Partials 4 4 Continue to review full report at Codecov.
|
abadger
force-pushed
the
adding-docs
branch
3 times, most recently
from
8195d7e to
e756821
Compare
|
This pull request introduces 9 alerts when merging e756821 into 36fcbe1 - view on LGTM.com new alerts:
|
abadger
force-pushed
the
adding-docs
branch
2 times, most recently
from
41c5b2d to
baaed44
Compare
Codecov Report
@@ Coverage Diff @@
## master #5 +/- ##
===========================================
+ Coverage 3.76% 15.25% +11.48%
===========================================
Files 17 5 -12
Lines 1646 400 -1246
Branches 318 43 -275
===========================================
- Hits 62 61 -1
+ Misses 1580 335 -1245
Partials 4 4 Continue to review full report at Codecov.
|
abadger
force-pushed
the
adding-docs
branch
9 times, most recently
from
509d74b to
d714c0c
Compare
antsibull/write_docs.py
Outdated
| except ValueError: | ||
| # Ansible doesn't give itself any names | ||
| namespace = 'ansible' | ||
| collection = 'builtins' |
There was a problem hiding this comment.
| collection = 'builtins' | |
| collection = 'builtin' |
The synthetic collection included in ansible-base is called ansible.builtin, not ansibe.builtins. (If you grep for it, you'll find several matches for ansible.builtin, but none for ansible.builtins.)
There was a problem hiding this comment.
Yeah, I saw this too. I've got the same simple fix queued, but I wondered whether I should modify the schemas to add ansible builtin to any DOCUMENTATION entry that only has a short name and then removing this code.
There was a problem hiding this comment.
Okay, after talking with nitzmahone about how the collection loader works, I don't think that the schema is the right place anymore. The reason is theoretical but I think it's valid.
Modules in ANSIBLE_LIBRARY (and same for the other plugin paths) are actually unknown to the collection loader. So to ansible, the plugins shipped with ansible-base are part of the synthetic ansible-builtin collection but the ones in ANSIBLE_LIBRARY path are known to not exist in a collection at all. The ansible-doc parser is not passing that information on to us.
If we normalized this in the schema, then we'd falsely be adding ANSIBLE_LIBRARY plugins into ansible.builtin. Since the idea for the schema is that it could be easily reused by other parties, I don't think we should perform this kludge there. I think the right place to fix up the plugin names is in the backend parser. Until we write our own, we have to rely on what ansible-doc does. what ithink that means is we should put the kludge into the ansible_doc backend. After we get the output back from ansible_doc, change the plugin names that need them to include ansible.builtins there.
There was a problem hiding this comment.
This strategy has now been implemented https://github.com/ansible-community/antsibull/pull/5/files#diff-d0fd94da5008596d8d48e47df3c1e89eR108
abadger
force-pushed
the
adding-docs
branch
2 times, most recently
from
3ca2744 to
d1377e4
Compare
|
The goal is to get this merged today so that we can have a test docsite build by next week. Towards that end, I've opened the following issues for known bugs in this PR:
I've also opened issues for all of the "TODO later" items. Once this passes the automated tests, it will get merged. |
[_] Build docs for stable
[x] Parse the collections from a antsibull deps file
[x] Download ansible-base that was used in the deps file
[x] Download collections at those versions
[x] Install the collections into the ansible-base that was downloaded
[x] Parse docs out of ansible-base plugins
[x] Parse docs out of collections
[x] Construct rst from parsed data
[x] Output to the right directory structure
[x] Construct index.rst from the parsed data
[_] Fix options output (full_path needs to be constructed)
[_] Fix linking between modules (the anchors are not easily constructable by M()
[_] Build docs for devel
[_] Parse the deps from an antsibull .in file
[_] Download the latest versions of those collections
[_] Git clone the latest version of ansible-base
[_] Build docs for a collection
[_] ?
[_] Build docs for a single plugin
[_] ?
Changes:
* Add type info for everything antsibull-docs uses.
* Move code to install collections to its own python module for reuse by
antsibull-docs
* Move some constants that are shared between antsibull-changelog and
antsibull-docs into a constants module.
* Move code for untarring tarballs to their own module for reuse with
antsibull-docs.
* Create a module that combines venv and sh functionality. Makes it
easier to run programs inside of a venv.
* Change changelog.ansible.get_documentable_plugins() to return a frozenset.
* Create a module for parsing documentation out of plugins.
* Normalize the documentation via a schema.
* Add the ability tto add ref entries via a `R()` macro in
DOCUMENTATION.
* Fix the vendored collections ImmutableDict to do equality testing
Adding a script which will extract docs from collections and format as rst. This script will also be usable by third parties who are looking to build documentation for their own websites.