wpilibsuite/sphinxext-remoteliteralinclude

Updating pypi page and possibly adding additional setup instructions

Closed this issue · 2 comments

First off, thank you for creating this package, it's awesome!

I think the documentation for how to use this extension could be improved/updated. I wasn't able to get the remoteliteralinclude directive working by just installing the package and then using the directive/tag. Maybe I messed something up there.

However, I was able to get it working by doing the following 2 steps:

  1. Adding from sphinxext.remoteliteralinclude import * to my conf.py file.
  2. Using the directive .. rli:: instead of .. remoteliteralinclude:: in my .rst files

It looks like the README.md file has the correct example with the rli directive. However, the pypi page has an example with the remoteliteralinclude directive.

It also might be worth adding some instruction about importing the extension in the conf.py file. This is probably obvious for people that are well versed in Sphinx, but it would be really helpful for people new to Sphinx such as myself.

Adding the python import is not necessary and not recommended as it can pull in some unwanted content. You simply need to add the extension to the list of extensions in your conf.py. Also, originally it was .. remoteliteralinclude, but I found that verbose and changed it to .. rli::. Unfortunately, I didn't add any backwards compatibility and just haven't gotten around to working on this extension in recent time. I'll see what I can do tonight.

Ahh, yeah I think I was getting myself mixed up between the old version and the new.

Also, I originally tried adding rli and remoteliteralinclude to the extensions list in my conf.py file, which didn't work. I just realized that it should be the name of the package sphinxext.remoteliteralinclude and not the directive name. That would probably be obvious to an experienced Sphinx user, but might be worth adding a comment about it for newbies like me. Up to you.

Thank you for your help!