Support for literalinclude

[ewu63]

Thanks for this extention! It looks super neat.

In our documentation, we mainly use literainclude blocks instead of having the code directly in the RST file, so that standalone Python scripts in the repo be run without needing to copy/paste. I was wondering if it's possible to support these blocks in addition to code blocks.

[felix-hilden]

Thanks for the suggestion!

Initially, I think it should be possible. I'll have a look at how it works and post back.

[felix-hilden]

Hi again, thanks for being patient. .. literalinclude: is very similar to code blocks, so it's definitely possible. And it even has language parameters that default to Python with syntax highlighting, so I don't think we're overstepping any boundaries there. So I'll get to it!

[felix-hilden]

Oh, you know what, it already works with the :language: py parameter! Since to Sphinx it's another literal block with a language parameter 😄 Would that be enough? Guessing, even a little bit, tends to make me a bit wary. We require the language spec in ordinary code blocks as well.

So you'd have:

.. literalinclude:: test.py
   :language: py

[ewu63]

Hey, thanks for the prompt reply! I tried that out for our documentation, and it sort of works. Our use case is probably a bit complex, as it also involves using the autolink-concat feature as well as intersphinx.

I've pushed up what I have to this PR, and the page that I modified is built here. I got the first two links to work, but subsequent ones failed:

/home/docs/checkouts/readthedocs.org/user_builds/mdolab-mach-aero/checkouts/76/machAeroTutorials/aero_pygeo.rst:40: WARNING: Inventory missing `numpy` when resolving `numpy` on line 1
/home/docs/checkouts/readthedocs.org/user_builds/mdolab-mach-aero/checkouts/76/machAeroTutorials/aero_pygeo.rst:40: WARNING: Inventory missing `pygeo` when resolving `pygeo` on line 2
/home/docs/checkouts/readthedocs.org/user_builds/mdolab-mach-aero/checkouts/76/machAeroTutorials/aero_pygeo.rst:47: WARNING: Inventory missing `len` when resolving `len` on line 2
/home/docs/checkouts/readthedocs.org/user_builds/mdolab-mach-aero/checkouts/76/machAeroTutorials/aero_pygeo.rst:80: WARNING: Inventory missing `numpy.zeros` when resolving `np.zeros` on line 5
/home/docs/checkouts/readthedocs.org/user_builds/mdolab-mach-aero/checkouts/76/machAeroTutorials/aero_pygeo.rst:103: WARNING: Could not resolve `wing.writeTecplot` on line 1
/home/docs/checkouts/readthedocs.org/user_builds/mdolab-mach-aero/checkouts/76/machAeroTutorials/aero_pygeo.rst:103: WARNING: Could not resolve `wing.writeIGES` on line 2
/home/docs/checkouts/readthedocs.org/user_builds/mdolab-mach-aero/checkouts/76/machAeroTutorials/aero_pygeo.rst:103: WARNING: Could not resolve `wing.writeTin` on line 3
WARNING: Cannot locate modules: 'len', 'numpy', 'pygeo'
  because of missing intersphinx or documentation entries

The numpy and len entries can be ignored, but I was hoping to get wing.writeTecplot, wing.writeIGES, and wing.writeTin linked correctly. The autodoc site for those are located here, and this is the conf.py that I use---it also imports a bunch of configurations from here.

Is there a good way to debug why the extension failed to resolve those references? There's also a warning of WARNING: Inventory missing pygeowhen resolvingpygeo on line 2 which is surprising since the links for the import and the invocation of pyGeo worked, but maybe that's indicative of some further issues.

[felix-hilden]

Okay, I'll try to help! But the parsing shouldn't have to do with concats or anything. This looks like a linking bug, since the class does have the methods documented and you do indeed concatenate the examples. But we do demonstrate similar functionality on our RTD front page :D And I tested locally that the concatenation has nothing to do with it. So is the class somehow special? Does the example link if it's as one piece?

BTW, the "missing pygeo" error is probably because the site is missing a module anchor from .. automodule:: pygeo since you .. currentmodule:: pygeo and then just document the class.

[ewu63]

Thanks for your help---please don't feel obligated to answer my questions since I know everyone who's working on FOSS is just doing this on their free time :)

The examples still don't work if I put everything together, so now I'm suspecting that it's something is wrong with the autodoc setup of pygeo, and that everything with the extension is probably working as expected. I tried a different example that does not involve pyGeo, and everything seems to be working there with literalinclude.

I never really figured out how to use autodoc properly I think, say if I want separate documentation pages for different classes/modules under the package pygeo, do I need currentmodule or automodule? Should I be using autoclass:: pygeo.pyGeo instead? Or do I need automodule:: pygeo at the top of each page?

[felix-hilden]

No worries! Knowing Sphinx there may be subtle differences between the two :D at least it can affect the naming (prefix), but the inventory entry, i.e. the anchor name seems to match. So I'm honestly not sure where to look next.

Maybe you could set up a toy project with similar documentation. That could reproduce the issue!

[ewu63]

Is there a way to figure out what reference codeautolink is trying to look for, for each of the warnings produced? I could then maybe cross-reference that with what's contained in my objects.inv to figure out what's going on.

[felix-hilden]

That could be useful debugging info! But for now this is the function responsible for hunting the type down. Maybe you can modify / debug it locally. I'll have a look at adding more info tomorrow!

[felix-hilden]

I included more debugging information in #106! You can use the git version until we release. I'll declare this issue done, since I'm pretty happy with how literalinclude works. But feel free to open another issue or a discussion entry (referencing this if you don't want to repeat yourself) if you still have problems! Or even ping me on your PR 😄

[ewu63]

Thanks a lot for the quick responses! Happy to close this issue since literalinclude works out of the box. Perhaps it would be a good idea to mention this in the docs somewhere, that this works not just with code-block but also literalinclude?

[felix-hilden]

Fair point!

[ewu63]

Even something quick like just adding a sentence or two in the basic example page should be good. That way, people who use the search function for it in the docs (as I did) would be able to find the info. I can also do this at some point but I'm fairly busy these days with my dissertation.

[felix-hilden]

I'm back after the weekend, so I'll take care of it then!