Rearrange CONTRIBUTING.md into devdoc chapter and add jldoctests page #58506
Conversation
Keno
force-pushed
the
codex/write-devdocs-page-on-jldoctests-best-practices
branch
from
a61c299 to
c9f6903
Compare
|
Although maybe this page doesn't go here, since the heading of the devdocs is "Documentation of Julia's internals". This is more of a "Contributor's guide" page. |
|
In fact, we already have a section on doctests in CONTRIBUTING.md that I forgot about: https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#doctests |
This moves the various sections of CONTRIBUTING.md into their own pages in a new "Contributor's Guide" chapter of the devdocs. I think this organization makes more sense as CONTRIBUTING.md is a bit of a weird mix, between widely applicable things (how to sign up to GitHub) and very niche things (e.g. how to prepare a backport). I think this also sets the stage for writing more specific documentation (e.g. my new jldoctest page) that would have been far too in-depth to put directly into CONTRIBUTING.md.
Keno
force-pushed
the
codex/write-devdocs-page-on-jldoctests-best-practices
branch
from
2737389 to
d333d8c
Compare
Keno
changed the title
|
Ok, I think the best way to do this is to just rearrange CONTRIBUTING.md into its own devdocs chapter (it already has a bit of a weird mix of super high level and super specific things) and then I can add this new page there. Adding @LilithHafner as reviewer for being the last person to rearrange CONTRIBUTING.md ;). |
Thanks copilot, good catch on both, you should believe in yourself more. |
|
@LilithHafner was your 👍 react a "yes, I think this is good", or a "ack, I've seen this, will take a look"? Either way is fine, but I wasn't sure. |
|
The latter |
|
Alright, take your time |
LilithHafner
left a comment
LilithHafner
left a comment
There was a problem hiding this comment.
This is a good change. I like the new organization.
Is d333d8c just moving things & eliminating the TOC or should I also be reviewing changes within the chunks of docs that are moved?
|
|
||
| * Review discussions on the [Julia Discourse forum](https://discourse.julialang.org). | ||
|
|
||
| * For more detailed tips, read the [submission guide](https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#submitting-contributions) below. |
| ## Setup code | ||
|
|
||
| Small setup expressions may be placed inline using the `setup =` option: | ||
|
|
||
| ```` | ||
| ```jldoctest; setup = :(using InteractiveUtils) | ||
| ... | ||
| ``` | ||
| ```` | ||
|
|
||
| For longer setup code or if multiple blocks require the same environment, use the | ||
| `DocTestSetup` meta block: | ||
|
|
||
| ```` | ||
| ```@meta | ||
| DocTestSetup = :(import Random; Random.seed!(1234)) | ||
| ``` | ||
| ```` | ||
|
|
||
| and disable it afterwards with | ||
|
|
||
| ```` | ||
| ```@meta | ||
| DocTestSetup = nothing | ||
| ``` | ||
| ```` | ||
|
|
||
| ## Maintaining state between snippets | ||
|
|
||
| Related doctest blocks can share state by giving them the same label after the | ||
| `jldoctest` keyword. The manual uses this pattern to demonstrate mutation: | ||
|
|
||
| ```` | ||
| ```jldoctest mutation_vs_rebind | ||
| julia> a = [1,2,3] | ||
| ... | ||
| ``` | ||
| ```` | ||
|
|
||
| and later | ||
|
|
||
| ```` | ||
| ```jldoctest mutation_vs_rebind | ||
| julia> a[1] = 42 | ||
| ... | ||
| ``` | ||
| ```` | ||
|
|
||
| Blocks with the same name execute sequentially during doctesting, so variables | ||
| created in the first block remain available in the following ones. | ||
|
|
||
| When a snippet needs to preserve its result for later examples, give it a label | ||
| and reuse that label. This avoids repeating setup code and mirrors a REPL | ||
| session more closely. |
There was a problem hiding this comment.
I think this section would be better as a link to https://documenter.juliadocs.org/stable/man/doctests/
There was a problem hiding this comment.
This section is mostly to tell the AI, which can't follow links (well the OpenAI one can't, the Google one can, but it's worse at its job). I can add the link in addition though.
There was a problem hiding this comment.
@LilithHafner raised this question to triage - there were no strong objections to duplicating the info. I'll add the link, but otherwise am planning to go ahead with this. We can always delete it later if the consensus swings the other way.
Largely just moving things. You flagged the one removal. |
This adds a new devdoc page on best practices for writing devdocs. A primary motivation is to feed this to AI agents when you ask them to write new devdocs for you, so that you don't have to teach them how to do that from scratch. If we don't think this is valuable enough in the main devdocs, we could consider an
aidevdocsfolder.