On 17.10.20 01:41, Mica Semrick wrote:
You have specifically pointed out where you think markdown is falling
short in this case.
For me MD vs Sphinx is mostly about roles, extensions, citations, line
comments, footnotes etc. that you have in Sphinx but not in MD.
MD was designed for writing texts on the Web. ReST + Sphinx was designed
for writing documentation.
Here is a longer version of that, written by someone else:
https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/
With that said: I prefer MD syntax over ReST any day as long as it
doesn't take anything away I think is standard for good documentation.
E.g. being able to have an index auto-generated.
Sadly it does. Worst, there is no real standard in MD.
CommonMarkdown is different everywhere. Maybe a feature you grew fond of
when using MD in Jupyter Notebooks' MD is not available on GiHub's MD etc.
> Feedback is welcome, but please try to make it actionable. We're
> aiming for improvement.
With the above in mind – if I were to start a documentation project now
I'd probably use this:
https://myst-parser.readthedocs.io/en/latest/
Which is kinda ReST + MD having a baby. :)
It would mean all the work you done could be used, mostly as-is.
But you would have all the bonuses of ReST + Spinx on top that MD +
Sphinx would not give you. Even if you switched from MD + Hugo to MD +
Sphinx.
Oh, and use readthedocs to handle building and serving.
Because, again, that is an ecosystem build for serving documentation as
static pages online.
Hugo is nice but it was meant to build static websites.
Which surely represent a superset, containing static online
documentation, but broad enough that it will leave many things to be
desired, sooner or later.
And btw: https://darktable.readthedocs.io/ is available. ;)
Beers,
.mm
P.S.: For context:
I wrote software documentation in MD several times during the last decade.
I wrote software documentation in ReST using Sphinx several time (that
was before Sphinx added MD support).
I also have BG writing docs in LaTex from way before.
With that being said I feel entitled to be opinionated about the subject.
And mind you, I am talking about the perspective of the writer, not the
user.
___________________________________________________________________________
darktable developer mailing list
to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
