Repository navigation
Finish modernization of the tutorials repo #53
Description
Activity
Once all the short term action items are done, we'll pull 54
Whoops, forgot to enable that, just need to add it to the conf
diff --git a/internal_use/docs/source/conf.py b/internal_use/docs/source/conf.py index 41ef378..35fd9e7 100644 --- a/internal_use/docs/source/conf.py +++ b/internal_use/docs/source/conf.py @@ -29,7 +29,7 @@ author = 'Imaging Platform' # ones. extensions = ['sphinx.ext.intersphinx', 'myst_parser'] locale_dirs = ['../locale/'] -myst_enable_extensions = ['colon_fence', 'dollarmath', 'linkify', 'substitution', 'tasklist'] +myst_enable_extensions = ['colon_fence', 'dollarmath', 'linkify', 'substitution', 'tasklist', 'html_image']Reacted by emigliettaOther option would be to use the attrs_inline,but you'll still need to add that to the conf, so this seems simpler for now
https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html#inline-images
Reacted by Beth CiminiDone! now inline images are display correctly!
I put the instructions in internal-use/docs/instructions.md
Nice, exciting we got this merged! A couple cleanup tasks outstanding:
- Two tutorials (3D Monolayer and 3D Nuclei), the translations done to date show up as in the old version of the file (from the
build_modernizationbranch) rather than the new version in transifex. No idea why, the rest moved over and now show as the translations done associated withmaster. There's apparently a way to fix it in the API, but since the fix should just be a bunch of copy-and-paste (and neither file is super long), and since some moved and some didn't, I think probably better to copy-and-paste. I removed the extra copies of all the other files, once the translations get moved over for those 2 I'll delete the extra copies there too. - "Upgrade" BS_Simp to now being called BeginnerSegmentation, and move or delete the previous version. We have a few tutorials up on the top level (Workstation, etc) that it might be time to just create a deprecated_tutorials folder to move anything not super-current into...
- Two tutorials (3D Monolayer and 3D Nuclei), the translations done to date show up as in the old version of the file (from the
sounds good! just one question, all these modifications should be done in the Build modernization branch?
Also, should we delete the BS_simplification branch? since it is already merged to Build modernization?Both those branches should now get deleted and work on #2 should start from a new clean branch! The first one will happen only in Transifex so no GH changes needed at this time.
Reacted by emiglietta


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