The easiest way to take advantage of the translation workflow we've ported over from bioimagingguide is to rather than build tutorials how we have been up until now (pandoc), we build them with Sphinx, where we can build either version with just a single flag switch. We can also bulk-build whole folders, and even easily make it so that you can access all the tutorials in a single page (this to me is the critical thing that keeps this from being an overengineering exercise). There are plugins we can use (see link and alternatives mentioned in it) to then also automate the PDF building, if we want. I'd love to eventually get to a place where we just make text edits in the markdown file, and then each tutorial builds itself in however many languages we support, makes the right zip files, puts them somewhere, etc, so all we need to do is worry about content and the rest takes care of itself. That might be a fun beginner-intro-to-GH-and-builds project.
Unfortunately a) we did not always structure things in a way that makes bulk-building a single file a great idea (some things have multiple top-row headings, for example) and b) Sphinx seems to take issue with the way we embed images sometimes for RST, etc. Fighting with RST at least preliminarily hasn't gone well, but since Sphinx supports MyST, which we know is super full-featured, this could be a better option.
So a few annoying things will need to get done, but for hopefully results we agree are worth it!
Once - short term
Per current tutorial - short term
Go through and fix up. This includes
- Making a single title-level title, and/or setting the title we want for the sidebar and main page in the
toc_en/index.rst file (see Translocation example)
- Making the heading structure something sensible in terms of level1s, level2s, etc
- Checking on how the import went and fixing where it went wrong. In the first one Esteban and I spot-checked, the combo of having
scale and width (or even width and height) made weird squishiness, and some things had heights in pixels some in inches, etc. Each figure should have width set only in terms of size parameters (plus possibly/probably align, alt, etc)
- Do this for
Eventually
The easiest way to take advantage of the translation workflow we've ported over from bioimagingguide is to rather than build tutorials how we have been up until now (pandoc), we build them with Sphinx, where we can build either version with just a single flag switch. We can also bulk-build whole folders, and even easily make it so that you can access all the tutorials in a single page (this to me is the critical thing that keeps this from being an overengineering exercise). There are plugins we can use (see link and alternatives mentioned in it) to then also automate the PDF building, if we want. I'd love to eventually get to a place where we just make text edits in the markdown file, and then each tutorial builds itself in however many languages we support, makes the right zip files, puts them somewhere, etc, so all we need to do is worry about content and the rest takes care of itself. That might be a fun beginner-intro-to-GH-and-builds project.
Unfortunately a) we did not always structure things in a way that makes bulk-building a single file a great idea (some things have multiple top-row headings, for example) and b) Sphinx seems to take issue with the way we embed images sometimes for RST, etc. Fighting with RST at least preliminarily hasn't gone well, but since Sphinx supports MyST, which we know is super full-featured, this could be a better option.
So a few annoying things will need to get done, but for hopefully results we agree are worth it!
Once - short term
sphinx-build -b html -D root_doc=toc_en/index . ../build/html, to build in Spanish runsphinx-build -b html -D language=es -D root_doc=toc_es/index . ../build/html_es' - I took a first pass in our internal lab wikiPer current tutorial - short term
Go through and fix up. This includes
toc_en/index.rstfile (see Translocation example)scaleandwidth(or evenwidthandheight) made weird squishiness, and some things had heights in pixels some in inches, etc. Each figure should havewidthset only in terms of size parameters (plus possibly/probablyalign,alt, etc)Eventually
sphinx-build -b gettext . _build/gettextthento make updated POTsphinx-intl update -p _build/gettext/POfiles