allow Markdown for docsrc documents - #5211
Conversation
2b1c802 to
347f1b4
Compare
rjbs
changed the title
|
The CI will failed until we've put cyrusimap/cyrus-docker#37 in the docker image |
elliefm
left a comment
elliefm
left a comment
There was a problem hiding this comment.
Looks good!
A few things still needed to complete the job:
- around line 2425 of configure.ac, add myst_parser to the rest of the "Documentation dependencies" outputs that are reported to the terminal
- also add it to the dependencies list in docsr/developer/compiling.rst. The deb package is called 'python3-myst-parser'
- changes file
|
I've added the configure.ac update — and realized we hadn't done that in the doxygen branch, so went and did that! Updated the compiling.rst I added a changes/next file, but I think I don't believe in my heart we need one. But that's a discussion for another time. It took 30 seconds, right? I've merged the cyrus-docker change to add myst, so the next CI run of this branch is likely to succeed. Then I spent some time wondering why my local build didn't work. It's because I didn't install myst_parser. Fixed that, stub page looks good. It's silly content, but real content later. |
elliefm
left a comment
elliefm
left a comment
There was a problem hiding this comment.
Looks good. One comment on the changes file but it's not any kind of blocker.
| Content for the documentation site (cyrusimap.org) can now be written in | ||
| Markdown. |
There was a problem hiding this comment.
So, from the point of view of someone installing, upgrading, or packaging Cyrus (i.e. the audience of the release notes), the interesting change is that they will now need myst-parser if they want to (re)build the documentation. Last time they built Cyrus, Cyrus didn't need it, so they probably don't just have it already. This is the kind of thing I would stick under the "Build changes" heading.
Being able to write documentation in markdown is interesting to people writing (or avoiding writing) documentation, but not to anyone else, I don't think.
There was a problem hiding this comment.
I have adjusted this bit!
We'll use this to build docs from Markdown.
This is a new TOC document that will list specs for our protocol extensions. Also, sieve.md, which is just a placeholder to show that this will all work. Next, we'll document the extensions.
2 participants
Woah, remember this old hunk of work?
This will make it possible to write some docs in Markdown. Although I have temporarily given up on converting everything, I think it will be useful for including some technical specifications that we currently write in Markdown elsewhere.