[WIP] Refactor and update to Documenter v1.0 #13
Conversation
- Writing methods are updated to use Documenter 1.0 and dispatch on markdown flavors defined by settings - MIME rendering is changed to method based dispatch on `render_mime` for more control and flexibility - New Markdown renderer types defined - Skeletons for inventory.jl Co-authored-by: Avik Pal <avikpal@mit.edu> Co-authored-by: Roger Luo <rogerluo.rl18@gmail.com>
asinghvi17
force-pushed
the
as/documenter-1.0
branch
from
f42fa9b
to
3c381db
Compare
This is sort of type piracy...it creates a struct, which parallels the fields of `Documenter.HTMLContext` that we care about. No behaviour in Documenter changes but the function is vulnerable to changes in Documenter internals.
| # * current working directory is the root directory of the project ("DocInventories") in this case | ||
| # * the documentation for the project has been built locally in `docs/build/` | ||
| # * the documentation has also been deployed online and is available at the `root_url` hard-coded in the script. Otherwise, do not call `check_url` | ||
| # * running on Unix (otherwise: adjust that path separator) |
There was a problem hiding this comment.
"Unix" isn't going to hold if for testing on Windows CI
|
Asking for comments here - is there a particular style people prefer, as a baseline, for docs-blocks in markdown? Currently they're wrapped in an HTML div, but there are other options. |
As long as that div has a descriptive class name so that these blocks can be addressed by CSS, that seems fine
What are the other options? |
|
I can add the class name, good point! Our other options are to go "pure Markdown" with the function name being a 6th-order heading, and the docs being separated by horizontal separators. I guess one can always provide functions to do both... |
|
I'd go with HTML for the time being. At least until a situation comes up where any of these markdown formats ultimately get processed to something other than HTML/Epub. Pure markdown has very limited semantics, though, so I'm not sure it would be reasonable to render docstrings that way. If anything, I would render them as a code block; but then that's not really what you want in Vitepress, so then you'd have another step translating that code block into HTML. That doesn't seem like a good idea. |
|
That's what the dispatch is for ;) - we can have them render in one way for "pure Markdown", and Vitepress can opt to change the particular rendering of docstrings without having to opt out of the whole |
|
Hi guys! Wrapping docstrings in code blocks is not a good idea because the content of a single docstring can be really rich and full of different markdown objects like headers, code blocks and even horizontal lines I suppose. So for separating docstrings it would be great to use some kind of commented special text (so that it cannot be seen after render by default). As long as Markdown doesn't support any real comments I suggested this option for separators: I searched what people use instead of comments in Markdown and found this as quite common syntax as analogue of commented line. |
These changes come mostly from LuxDL/DocumenterVitepress.jl where they are already tested and deployed in several repos. The only new stuff is the inventory writing.
render_mimefor more control and flexibilityTODO: