5

Apologies - this is a complete n00b question:

I have a couple of python scripts with no .py extension.

How do I convince Sphinx that it should document that script? Example error:

/home/XXX/YYYYY/development/dst/build/index.rst:25: (WARNING/2) autodoc can't import/find module 'site_scons.random', it reported error: "No module named random", please check your spelling and sys.path

user2573436
  • 79
  • 9

3 Answers3

2

In order for your script to be a module, it needs to include the .py suffix. From the Python docs:

A module is a file containing Python definitions and statements. The file name is the module name with the suffix .py appended.

Without giving it the suffix, Sphinx won't be able to import it to generate documentation using automodule.

dirn
  • 19,454
  • 5
  • 69
  • 74
  • Cheers So sphinx is a module-documentation package. Surprised, as there must be a lot of scripts out there which need documenting. Back to the drawing board. – user2573436 Jan 09 '14 at 09:33
  • 1
    You can use it to write your own documentation. You just can't use `automodule` with something that isn't a module. – dirn Jan 09 '14 at 14:16
  • 2
    The documentation at http://www.sphinx-doc.org/en/stable/ext/autodoc.html says "If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition." This gives me hope that there is a way to document scripts. – krumpelstiltskin Feb 24 '16 at 09:29
0

If you don't want your script to end with a .py file extension you can also try the following.

You can write your original script into a .py file and create another executable (bash script) file that just executes your .py file. That way, you can document the script (the .py) file using sphinx and still execute it through the other executable file.

Dharman
  • 30,962
  • 25
  • 85
  • 135
fgoudra
  • 751
  • 8
  • 23
0

As mentioned by @dirn, a module requires a .py extension to be considered as such.

An alternate solution that I think is cleaner, though it requires more work:

  • Create a directory named links on your Sphinx root folder (that is, it will be a sibling to source and build)
  • On that directory, create relative links to your scripts, adding .py to their names
  • Add this new directory to the Python PATH on conf.py, under Path setup: sys.path.insert(0, os.path.abspath('../links'))
  • Now, you can use something like .. automodule:: my_command to have your script read as a module and documented.

A sample project would look like this:

proj_root/
proj_root/doc              # Sphinx root
proj_root/doc/build
proj_root/doc/links        # Remember to version this
proj_root/doc/links/my_command.py -> ../../bin/my_command
proj_root/doc/source
proj_root/doc/source/conf.py
proj_root/bin
proj_root/bin/my_command   # Actual code

The advantage I see for this method is that you do not polute your bin directory with .py files that are just duplicates of the actual scripts.

One could probably also try to hack this through the imp module to get it, but I think that would be uglier. I haven't tried that.

caxcaxcoatl
  • 8,472
  • 1
  • 13
  • 21