Finish modernization of the tutorials repo

[bethac07]

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

• Run all the RSTs through rst-to-myst to turn them into MDs
• Run all the POT and PO files through a quick find-and-replace to change rst to md everywhere
• Set up conf.py and index.rst files accordingly
• Move new build instructions to somewhere better than right here right now, which is 'new build instructions are to cd into source, to build in English run sphinx-build -b html -D root_doc=toc_en/index . ../build/html, to build in Spanish run sphinx-build -b html -D language=es -D root_doc=toc_es/index . ../build/html_es ' - I took a first pass in our internal lab wiki

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
  • 3D Monolayer
  • 3D Nuclei
  • Adv Seg
  • Beginner Seg
  • FISH
  • Pixel Classification
  • QC
  • Translocation
  • Unmix Colors

Eventually

• As tutorials are finished translating, add them to the language toc page. If we add more languages, we just add more tocs
• Set up some sort of automated build script that on push of edited content
  • Runs sphinx-build -b gettext . _build/gettext then sphinx-intl update -p _build/gettext to make updated POT/PO files
  • Runs building of all languages to PDFs
  • Run a script that automatically builds the distribution materials for that tutorial and puts it somewhere helpful (AWS?)
• Figure out if, and if so, where, we want to serve the web pages that have all tutorials
• Go away from the current theme to something more fun, if we feel like

[bethac07]

Once all the short term action items are done, we'll pull 54

[emiglietta]

When making the .html files, the images inserted in line with the text don't show properly

Although in the preview of VS Code, they appear normally:

[bethac07]

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']

[bethac07]

Other 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

[emiglietta]

Done! now inline images are display correctly!

[emiglietta]

I put the instructions in internal-use/docs/instructions.md

[bethac07]

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_modernization branch) rather than the new version in transifex. No idea why, the rest moved over and now show as the translations done associated with master . 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...

[emiglietta]

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?

[bethac07]

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.