Web version

[DannyDannyDanny]

Could you consider having a web version? i.e through github pages?

[rougier]

It is not yet planned but it might be possible using the RST sources.

[joepio]

Some options:

StaticNinja https://staticjinja.readthedocs.io/en/stable/index.html

Sphinx https://github.com/pydanny/restructuredtext/blob/master/sphinx_tutorial.rst

[rougier]

I don't have too much time for doing that but I would welcome a PR.

[DannyDannyDanny]

I've wanted to try sphinx for a while. I've forked the repo. I'll let #51 inspire me and add to scripts/ directory. I've opted to expand the makefile to build the sphinx docs.

Update 1

I've got a web version up and running here.
Follow the roadmap to see how its going!

image file not readable warnings

During the build, sphinx throws ~400 warnings that mostly look like this:

xxx/scientific-visualization-book/rst/00-introduction.rst:22: WARNING: image file not readable: rst/introduction/visualization-landscape.pdf
xxx/scientific-visualization-book/rst/00-introduction.rst:43: WARNING: image file not readable: rst/introduction/matplotlib-timeline.pdf
xxx/scientific-visualization-book/rst/00-introduction.rst:68: WARNING: image file not readable: rst/introduction/black-hole.jpg

It seems several of the rst files reference the wrong directories. I have moved the contents of figures/ into rst/ to resolve these warnings. Maybe there's a more elegant way. I am open to suggestions!

[rougier]

Oh nice! Thank you very much for your effort. I think the style could be fixed but that's a minor point.
For the 400 warnings, it's probably Sphinx configuration problem with relative paths. Note that for the latex compiling, I have the line \graphicspath{{../figures/}{../cover/}} that instructs latex to look for image in these two directories.

[labdmitriy]

More and more formats of the latest version of the book are created, @DannyDannyDanny great work :)

Maybe our efforts can be combined in the future and as an idea to create Jupyterbook version of the book. I haven't studied this framework thoroughly but it has at least several nice properties:

• It supports MyST and RST
• It is based on Sphinx
• You can use Jupyter Notebooks for reproducibility

@rougier @DannyDannyDanny What do you think about this idea, how difficult will it be?

Now I am studying the book, and converting the code to Jupyter Notebooks for experiments here, and it has its own subtleties (like proper DPI fixing and turning off auto tight layout to properly display output images) but it seems that I found the solutions for it.
I plan to study the whole book in this way, and I will finish Chapter 2 soon, so if this idea is interesting for you we could arrange about:

• The structure of this book
• RST/Sphinx part format
• Jupyter part format

[paniterka]

Hi guys, just tuning in to throw another suggestion besides Jupyterbook. I mean Quarto https://quarto.org/ - it's a new project developed by the RMarkdown team and it is a cross-platform, cross-language tool to publish interactive articles, books, presentations etc. based on .md, .ipynb and some other formats (also .rst as far as I can see). I have not tried out the book renderer, only the article renderer, but it seems to be pretty powerful and better with every release. Besides HTML you can also compile to PDF via pandoc from the same sources. My gut feeling is Quarto is going to replace the Jupyterbook in the future because of robustness, so maybe it'd be a better choice.

[DannyDannyDanny]

Reply-to @rougier

Note that for the latex compiling, I have the line \graphicspath{{../figures/}{../cover/}} that instructs latex to look for image in these two directories.

Ah! I was wondering how on earth the rst files were referencing the figures folder. This makes sense but isn't very ((nice)) for sphinx as the relative path doesn't actually reach.

To make it work in sphinx one of the following changes has to be made:

• Option 1: (easy but not so nice) move contents of figures/ into rst/
• Option 2: (nice but not so easy) use absolute paths for figure references

I've already implemented Option 1 but I'm reverting it in favor of implementing Option 2.

An example of Option 2 in rst/00-introduction.py#L19 looks like:

.. # BEFORE
.. figure:: introduction/visualization-landscape.pdf
   :width: 100%

.. # AFTER
.. figure:: /figures/introduction/visualization-landscape.pdf
   :width: 100%

If the latex book still compiles after implementing option 2, then that would be the best solution IMO.

[DannyDannyDanny]

reply-to @labdmitriy

Thanks! I think the idea is great, but I'm already worried I've taken a bigger bite than I can chew with this issue. I'd like to descope it from this issue to start with and keep it in the backlog for now.

Perhaps notebooks with the exercises can be added as an extra resource for readers to explore but I suggest we move that discussion to a separate issue 💬

[DannyDannyDanny]

reply-to @paniterka

Looks like a promising project. I'm going to continue working on the web version in sphinx for now. Perhaps one day Quarto will overtake Jupyter and maybe even Sphinx. But judging by their github stats I don't think that day is coming later rather than sooner if at all 😉

[rougier]

Sorry for late reply. Option 1 seems to be the most straighforward because it could be a simple symbolic link and you do not have to change the actual structure.

[DannyDannyDanny]

@rougier

If i implement option 1, I'll have to edit the import path \graphicspath{{../figures/}{../cover/}} to preserve LaTeX compiling. Is that alright?

PDF -> SVG

On an somewhat related note, PDFs do not render directly on the webpages. I'm going to convert (or rebuild) all figures/**/*.pdf files to PNG or SVG. I'm going to prefer SVG where possible.

Bad Relative paths (discovery)

All scripts in code/ are two directories down from the repo root and most of them contain plt.savefig("../../figures... to produce images inside of figures/ which is fine. But some scripts omit the relative path ../../ and thereby generate images under the code/ directory.

Most of the culprit scripts can be identified with grep -E "savefig\(\"[a-z]" code/**/*.py. This python scripts finds all culprits.

Fix bad relative paths actionable items 🔨

• code/showcases/mandelbrot.py should contain ../../ (depth = 2) 🔨
  • L50: plt.savefig("mandelbrot.png", dpi=600)
  • Conclusion: change to plt.savefig("../../figures/showcases/mandelbrot.png", 🔨
• code/colors/stacked-plots.py should contain ../../ (depth = 2), observed:
  • L275: plt.savefig("../figures/stacked-plots.pdf")
  • file exists with ll ./**/stacked-plots.pdf:
    • /docs/_images/stacked-plots.pdf <--- what's with this _images dir?
    • /figures/colors/stacked-plots.pdf
  • file references with grep -r -E 'stacked-plots.pdf':
    • ./rst/colors.rst:.. figure:: /figures/colors/stacked-plots.pdf
  • Conclusion:
    • change to plt.savefig("../../figures/colors/stacked-plots.pdf", 🔨
    • change .pdf to .png in line above and in references 🔨
• code/unsorted/3d/platonic-solids.py 🔨
  • L331: plt.savefig("platonic-solids.png", dpi=300)
  • conclusion - change to plt.savefig("../../../images/platonic-solids.png", dpi=300)
  • L332: plt.savefig("platonic-solids.pdf")
  • conclusion - remove line ⚠️

Scripts produce unused images (discovery)

Some scripts below the code/ directory produce images that are not used anywhere.

For example the code/animation/less-is-more.py file produces images with the pattern frame-*.png. No files with that pattern exist in the repo and no files in the repo reference files with that pattern.

Delete scripts that produce unused figures 🔥

• code/animation/less-is-more.py 🔥
• code/showcases/escher-movie.py 🔥
• code/beyond/tikz-dashes.py 🔥
  • delete figures/beyond/tikz-dashes.pdf 🔥
• code/anatomy/pixel-font.py 🔥
• code/reference/axes-adjustment.py 🔥
• code/reference/tick-locator.py 🔥
• code/reference/colormap-qualitative.py 🔥
• code/reference/marker.py 🔥
• code/reference/tick-formatter.py 🔥
• code/reference/colormap-sequential-1.py 🔥
• code/reference/hatch.py 🔥
• code/reference/colormap-sequential-2.py 🔥
• code/reference/colormap-uniform.py 🔥
• code/reference/collection.py 🔥
• code/reference/font.py 🔥
• code/reference/text-alignment.py 🔥
• code/reference/line.py 🔥
• code/reference/scale.py 🔥
• code/reference/colormap-diverging.py 🔥
• code/unsorted/advanced-linestyles.py 🔥
• code/unsorted/stacked-bars.py 🔥
• code/unsorted/earthquakes.py 🔥
• code/unsorted/metropolis.py 🔥
• code/unsorted/3d/scatter.py 🔥
• code/unsorted/3d/scatter.py 🔥

[rougier]

Very late again, sorry. Thanks for the detailed update.

1. Since PDF needs to be converted to PNG or SVG, maybe it is simpler to save each figure twice, one PDF for latex and on PNG/SVG for web.

2. Code the do not save their output to ../../figures are certainly error.

3. The scripts that produce figure that are not in the book are ok. I may have decided to not include some code ultimately. The reference code is supposed to be included at the end of the book and I'm surprised you flagged them as unused (or maybe it was for an earlier version). For the web version, we can directly use the cheatsheets from matplotlib. I mostly resize them such that they're still readable for the printed book.