Open bethac07 opened 8 months ago
Once all the short term action items are done, we'll pull 54
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:
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']
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
Done! 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:
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.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.
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.rst
file (see Translocation example)scale
andwidth
(or evenwidth
andheight
) made weird squishiness, and some things had heights in pixels some in inches, etc. Each figure should havewidth
set only in terms of size parameters (plus possibly/probablyalign
,alt
, etc)Eventually
sphinx-build -b gettext . _build/gettext
thento make updated POTsphinx-intl update -p _build/gettext
/POfiles