We already use it in the documentation examples, and in my opinion that makes it part of the public API, since if we change it in a breaking way, then the documented examples break, and that seems like a breaking change.
The way the docs are currently setup, only exported functions show up, so currently it dosen't show up
That's why I want to do this in this PR, since I refer to it in my introduction
You really need it to use the DAG functionality (big part of the package!)
So IMO we should just accept it is part of the public API and do a breaking change to change if when/if we want to do that.
Abstract interface docs
Regarding the refactoring of the abstract interface docs, here I've dropped @autodocs in favor of choosing the order and putting section headings in-between different parts of the docs. This doesn't run the risk of missing things, because we have strict=true set, so if we add new documented & exported functions to that page, Documenter will error at build time. I tested this with a new exported/documented function abc added to abstract.jl:
┌ Error: 1 docstring not included in the manual:
│
│ TransformSpecifications.abc :: Tuple{}
│
│ These are docstrings in the checked modules (configured with the modules keyword)
│ that are not included in @docs or @autodocs blocks.
└ @ Documenter.DocChecks ~/.julia/packages/Documenter/bYYzK/src/Utilities/Utilities.jl:32
BTW in general I feel like autodocs is awesome for getting docs off the ground quickly, but this sort of more manual ordering/subcategorizing with additional written text ends up making for nicer docs in the end, once there is some time to actually work on them. I was thinking of doing this treatment for all of them but decided I felt done working on docs for now 😄.
Introduction
Why write an opinioned introduction specifying a workflow, in contrast to the more hands-off approach used elsewhere in the docs? I felt like this would help my team and others dive in quickly, to try to answer "but how do I actually do it" more directly, without necessarily needing the implementer to fully appreciate the abstract interface / design philosophy / etc before getting started.
Some explanations for choices made in this PR:
input_assemblerWhy export
input_assemblerif it is temporary?So IMO we should just accept it is part of the public API and do a breaking change to change if when/if we want to do that.
Abstract interface docs
Regarding the refactoring of the abstract interface docs, here I've dropped
@autodocsin favor of choosing the order and putting section headings in-between different parts of the docs. This doesn't run the risk of missing things, because we havestrict=trueset, so if we add new documented & exported functions to that page, Documenter will error at build time. I tested this with a new exported/documented functionabcadded toabstract.jl:BTW in general I feel like autodocs is awesome for getting docs off the ground quickly, but this sort of more manual ordering/subcategorizing with additional written text ends up making for nicer docs in the end, once there is some time to actually work on them. I was thinking of doing this treatment for all of them but decided I felt done working on docs for now 😄.
Introduction
Why write an opinioned introduction specifying a workflow, in contrast to the more hands-off approach used elsewhere in the docs? I felt like this would help my team and others dive in quickly, to try to answer "but how do I actually do it" more directly, without necessarily needing the implementer to fully appreciate the abstract interface / design philosophy / etc before getting started.