doc: convert internals docs to readthedocs #5939
Conversation
There was a problem hiding this comment.
LGTM! Good idea. Should the README in the broker dir be replaced with some breadcrumbs pointing to the new docs location, since a developer working on code might be more apt to look there first?
Eh, I guess it was under broker/doc/README so probably not necessary, just a thought.
garlick
changed the title
Problem: there is a wiki document describing KVS internals that nobody knows is there. Create a new "resources for flux developers" section in the flux-core docs and add this content as a KVS chapter.
Problem: there is a markdown document in broker source describing some aspects of its internals that nobody knows is there. Add this content as a broker chapter in the resources for flux developers section.
Problem: the typo checker called out a typo in something I
added to the dictionary:
Warning: "ND" should be "AND".
error: `ND` should be `AND`
--> ./doc/test/spell.en.pws:903:1
|
903 | NDIyCg
| ^^
|
This was a fragment of a UUID I was fored to add.
Exclude the dictonary from the typo check.
|
Thanks, yeah I think that README buried down in the sources was probably invisible so leaving a pointer there is likely not helpful. I fixed up a few typos and formatting errors I spotted this morning with fresh eyes, and added the new files to the Makefile.am (oops). Probably good to merge now so I'll set MWP. |
I tend to find those when I'm actually working on code, since a README in the current directory is actually quite obvious, whereas it may not occur to the developer to go back to the top level and look under docs for current directory developer information. |
Ah OK, well maybe I'll go ahead and add README.md files in the kvs and broker source dirs then! |
|
I don't think that's necessary, I was just explaining myself! |
Problem: developers might not think to consult the flux-core readthedocs pages for design notes. Add a README.md in the kvs and broker source directories for them to stumble over.
|
NP. Your counterexample disproved my theory! |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #5939 +/- ##
==========================================
+ Coverage 83.35% 83.37% +0.01%
==========================================
Files 514 514
Lines 83105 83105
==========================================
+ Hits 69272 69288 +16
+ Misses 13833 13817 -16 |
Problem: there are some flux-core internals documentation that nobody knows about here and here.
Add a Resources for Flux Developers section to the flux-core docs and convert those documents to chapters in it.
These docs do need an update but it's a start.