Examples in the online documentation about linfa HOT 4 CLOSED

Thank you @robmoss! I have included the tutorials in the documentation and updated it on readthedocs.

from linfa.

Thank you for these comments.

• I have included the code in the examples using the literalinclude directive as suggested.
• That RCR example uses annealing, so it is normal for the loss to increase going from t=0 to t=1, instead of being reduced monotonically like for the other examples. I have added a comment so this is more clear.
• I tried the nbsphinx extension to render notebooks, but I get a large number of errors and warning, like these below:

WARNING: Block quote ends without a blank line; unexpected unindent.
ERROR: Unexpected indentation.

I'm trying to fix these problem. Have you seen them before?

from linfa.

Hi @daneschi

That RCR example uses annealing, so it is normal for the loss to increase going from t=0 to t=1, instead of being reduced monotonically like for the other examples. I have added a comment so this is more clear.

Thanks very much for the clarification, I was thoroughly confused!

I tried the nbsphinx extension to render notebooks, but I get a large number of errors and warning [...] Have you seen them before?

I haven't used the nbsphinx extension myself, but I've just given it a try and found a few things:

1. I needed to install nbsphinx (it's not listed in docs/requirements.txt).
   • I also installed ipython (also not listed) to avoid some warnings about syntax highlighting.
   • I also removed the numpy version in docs/requirements.txt so that it could install a newer version — otherwise it would try to build numpy from source when using Python 3.10.
2. The nbsphinx docs say to add the file names of your notebooks (without the .ipynb extension) to the toctree directive, rather than creating a .rst file and using the include directive.
   • I suspect this was the cause of the "unexpected indentation" error message.
3. When I added the notebook files to the toctree in docs/content/num_examples.rst, sphinx complained that it couldn't find the referenced images (which are in ./tutorial).
   • I resolved this by moving the tutorial directory to docs/content/tutorial.
   • The notebook links in README.md would need to be updated.

The toctree in docs/contents/num_examples.rst now looks like this:

.. toctree::
   :maxdepth: 2

   tutorial/tutorial_linfa_2d
   tutorial/tutorial_linfa_3d
   trivial
   ...

After these steps, I was able to build the documentation and view the notebooks!

There is still one warning:

MissingIDFieldWarning: Cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.
  validate(nb)

The good news is that this can be resolved relatively easily.

from linfa.

The tutorials look great!

from linfa.