| cardoe | Can we use markdown in our existing docs? Or somehow have parts in markdown? I only ask because tools like helm-doc generate markdown and I would want to use that as output for openstack-helm. | 11:12 |
|---|---|---|
| fungi | cardoe: you might be able to use pandoc to convert markdown to restructuredtext | 12:18 |
| fungi | could be done as a sphinx plugin to automatically integrate it during docs build | 12:18 |
| fungi | something like `pandoc --from=markdown --to=rst --output=foo.rst foo.md` | 12:19 |
| fungi | oh, even easier, if you include the myst-parser extension in your project's conf.py then sphinx will be able to ingest markdown directly | 12:28 |
| fungi | cardoe: https://www.sphinx-doc.org/en/master/usage/markdown.html | 12:29 |
| tkajinam | ianychoi, ^^^ this might be useful for our past conversation about translation (which may require markdown instead of rst) | 12:32 |
| tkajinam | I know it was mentioned for a different purpose. sorry for the noise ! | 12:32 |
| fungi | just be aware that markdown and sphinx-augmented restructuredtext are not equivalent featureset-wise, so any conversions back and forth between them will probably be lossy unless you stick to a strict intersection of their respective features | 12:41 |
| bauzas | tkajinam: no, this was for the other way, ianychoi did some work on md translation but I was saying that nova doc was restructuredtext hence the need to change the translation | 12:44 |
| bauzas | for sure he could use pandoc to transform rst to md and then run its translation engine, but I'd prefer to keep translated docs with the same format than the original one | 12:45 |
| tkajinam | what I thought was we may take similar (but not same) approach and convert rst to md and tralsate md, then give md to sphinx to build translation doc, if using rst becomes the real blocker for the work | 12:48 |
| tkajinam | but I agree in general we should avoid that conversion which may mess up things | 12:48 |
| bauzas | well, rst markups are easy to identify | 12:49 |
| bauzas | so I assume ian wouldn't have a lot of problems to adapt his translation script to rst | 12:49 |
| bauzas | and again, I wouldn't want the docs to diverge more than just the translated sentences | 12:50 |
| cardoe | Thanks fungi. Just trying to come up with a better way to keep the docs aligned with the code, so to speak. | 12:58 |
| fungi | cardoe: possibly better still, you can template the output from helm-docs to create restructuredtext instead of markdown, looks like? an example i spotted: https://github.com/Mellanox/network-operator-docs/blob/main/Makefile#L86-L88 | 13:18 |
| fungi | seems like they just supply a custom template file on the command line | 13:19 |
| cardoe | That's probably the best idea. Thanks for that. | 13:20 |
| fungi | also you could do that in a custom sphinx extension so it all just happens magically when you perform your docs build | 13:25 |
| *** avanzaghi16 is now known as avanzaghi1 | 13:32 | |
| clarkb | I don't think we actually require rst though? | 14:53 |
| clarkb | (or sphinx) | 14:53 |
| clarkb | oh nevermind we do require sphinx in the pti | 14:54 |
| *** jjung_ is now known as jjung | 16:35 | |
| *** amorin_ is now known as amorin | 17:35 | |
| -opendevstatus- NOTICE: The Gerrit service on review.opendev.org will be offline momentarily at 20:30 utc (half an hour from now) to apply a configuration change | 20:03 | |
| -opendevstatus- NOTICE: The Gerrit service on review.opendev.org will be offline momentarily to apply a configuration change | 20:32 | |
| ianychoi | Thank you @tkajinam and all. I don't want to change current OpenStack documentation behavior with rst & PTI to something other - I say how we migrated from xmldoc to rst around 2015 which required huge efforts. Also, from AI perspective, I believe that it would be just a matter of different syntaxes. | 23:56 |
| ianychoi | s/say/saw | 23:56 |
Generated by irclog2html.py 2.17.3 by Marius Gedminas - find it at https://mg.pov.lt/irclog2html/!