Full Circle Magazine FR

Ceci est une ancienne révision du document !

More Mysteries of the Sphinx

Greetings fellow Sentient Lifeforms. Beaming yet again from somewhere in time and space, I come again to, hopefully, provide more well needed information. (If you are not a Sentient Lifeform, I do not intend to withhold this from you, so feel free to attempt to read this.)

This month's article was inspired by one of the PAGE users on the PAGE Discord forum and someone whom I consider a good friend, Professor Roberto Machorro Mejía, who started using PAGE last school year. He teaches at UNAM, a public university, the largest in Mexico. He was using PAGE to create a GUI for a project he and his students were working on. Long story short, he has been reading Full Circle Magazine for a while now and he sent me a note that he really enjoyed my article on Sphinx in last month's issue. He was wondering, however, if Sphinx worked directly on a source file. So, I decided to write about how to make this happen.

I created a dummy program that really does nothing much but has functions that have Python Docstrings that can be used by Sphinx to “automatically document” the functions in the generated HTML or EPUB files.

Creating the docstrings that are needed to do this is very simple, but you need to remember to use the docstrings in every function, no matter how simple. If you don’t, you’ll probably have to go back and update the source file.

So, it all starts with your source code. If you use PAGE to create your GUI program, you don’t need to do anything to the PAGE .tcl file or the Python GUI.py file. The only file you need to concern yourself with is the support.py file.

One other thing to note, I’m using the bizstyle theme for Sphinx. If you decide to use a different Sphinx theme, your document won’t match the images that I’ve included here.

The docstring

The docstring is simply a section of your source code that starts and ends with three double quotes and in between is pretty much free-form information. However, for Sphinx to grab the information, there needs to be a few special lines. Here (next page, top right) is a snippet of what you can expect to provide…

Of course the first line is the function definition. Then we start the docstring with the three double quotes.

The next line is a description of what the function is for, which must be a single line. Then any parameters need to be documented using the format:

:param {parameter name}: description of parameter

:type {parameter name}: parameter type

…

Then what the function returns:

:return: description of the return value

If there is more than one parameter, simply repeat the param and type keys.

For more information on Docstrings, you can follow this link https://peps.python.org/pep-0257/#abstract

Doing it Manually

Of course you can do the documentation of your functions and methods manually. I'll create a “dummy” entry for a fictitious Sphinx document.

This is just the description that I would put into the fictitious index.rst file…

One of the best things about the program is for the user to have the ability to change themes at any time to any theme in the theme folder. Of course, these are all .tcl themes. Use the load_tcl_themes function to generate a list of all of the themes, then load this into a TCombobox values property. Then bind the virtual «ComboboxSelected» event to the TCombobox providing a callback function whenever the user selects something from the TCombobox list. Here is the ``sphinxDemo1_support.on_ComboSelect()`` function

Now we describe the function using the .. py:function:: directive.

You can see that this is very similar to the docstring information that I suggested you place into the source code, but manually entered into the index.rst Sphinx file (right).

Here (next page, top right) is how it will look in your HTML file. That’s a lot of work to do, especially if the code has already been documented using docstrings.

Doing it Automatically

In order to take advantage of the automatic documentation abilities of Sphinx, you will need to do a little bit of preparation. You will need to modify the conf.py file and add at least one extra .rst file to the /sphinx/docs/source folder.

The changes need to go into the conf.py file. These lines (right) need to go somewhere around line 16.

The most important line is the one that starts with

sys.path.append()

This is the fully qualified path to your source code. You don’t need to enter the filename(s) at this point, just the path.

The other important part is the extensions section. You will need to have all four lines in the list.

Now you just need to add one line to your index.rst file for each function you want Sphinx to document.

.. autofunction:: sphinxDemo1_support.load_tcl_themes

Of course, you can add text before or after this line, but here is what the output will look like. (I included the first line, just to make it flow better). See image bottom left.

Adding an Autosummary You need to create an extra .rst file named something like “api.rst”. In it you place just a few lines…

API

 :toctree: generated

 sphinxDemo1_support

 :maxdepth: 2

 :caption: Contents:

 api