Build System Docs #7544
Build System Docs #7544
Conversation
Codecov Report
|
|
let me know when you'd like me to review |
I think what I really want to know is if I should bother translating it to RST |
|
If it works (in the sense of appearing correctly in the TOC and having headers etc formatted consistently) I don't think it's necessary |
|
Then it's ready! |
Told you it would 😉 I'm not very well versed in the build system engineering, so I cannot really comment on the content of these docs until I manage the time to do more than click the Just a few comments regarding the writing and structure:
No need to go deeper in the language style edits at this point: dev docs are the result of many voices and writing styles that would require a major push to fully edit, revise and update. Just bumped into a phrase with |
I think it's fine to lead with the FAQs if they are in fact frequently asked. Might actually spell it out though. However, the nesting goes too deep. I think the "Architecture" section can be flattened significantly, leaving an outline like:
|
|
I actually put in the FAQ's based on the issue that spurred the docs: Based on the fact that those were put in there, I just assumed they were "frequently asked". I can rename or move the section if y'all think it's necessary 🤷♂️ |
Also changing main header name
|
That nesting might not make the most sense, I think. Pipelines Shouldn't all be at the same conceptual "level" IMO Pipelines is describing LE's use of pipelines. Orchestration, block steps, and release builds are all children of that concept; they don't make a lot of sense out of the overarching context of "LE's use of pipelines". That's also why it's named that way. Pipelines themselves were defined in the Buildkite section. We're doing things a little differently, making use of niche features that aren't well documented in Buildkite's docs. |
|
This is what I went with: |
|
Looks good to me 💯, but I'll leave the last word to @indirectlylit! |
|
Checking travis errors before merge |
Summary
Was surprised to find that sphinx parsed and converted Markdown, too!
Can leave as is or begin converting to rst, but structure will likely remain the same.
Reviewer guidance
make docs, then check out the build HTML under "Build System"References
resolves #7089
Contributor Checklist
PR process:
Testing:
Reviewer Checklist
yarnandpip)