search

qutip / qutip-doc

QuTiP documentation
36 stars 58 forks source link

Ipython directive breaks for functions #64

Closed quantshah closed 3 years ago

quantshah commented 5 years ago

The sphinx Ipython directive parser breaks for functions. See https://github.com/ipython/ipython/issues/11362

This breaks our documentation build as the code blocks in qutip-doc/guide/dynamics/dynamics-bloch-redfield.rst define some functions which cannot be produced by the Ipython directive. I spent a lot of time trying to make this work but to no avail.

I have a completely new version of the docs where I setup Sphinx from scratch which does not require the Ipython directive to run. The only catch is that we have to manually run the code blocks and generate the output and put them in the docs. I am trying to find other automated ways but would actually be happy to move from Ipython and just use the doc-test directive provided by Sphinx.

@nathanshammah @ajgpitch Let me know what do you think? It is time we update the documentation generator.

ajgpitch commented 5 years ago

The IPython stuff has caused me lots of headaches when building the docs. I would be happy to see the IPython requirement go altogether, if that is possible, if we think it is going to be more reliable.

Things to consider:

  1. A lot of our output is plots - are these going to work?
  2. Some may think the output less pretty, maybe we don't get the syntax highlighting?

Perhaps a good start would be to make a PR that contains some kind or test page in the docs where we can review and compare the output of both, before we launch into changing everything to doc-test directive?