PyCode is suitable to create documentation relative to your Python code. It allows you to embed Python scripts hosted in a remote public repository such as Bitbucket or GitHub.

Actually PyCode allows to embeds all types of scripting language supported by GeSHi ¹⁾, but with some limitations.

The following table shows what you can do with PyCode:

As you can see, there are some features that are specific only for Python script because PyCode was developed bearing in mind the Python syntax whose strong point is the use of indented code to mark where a code block starts and stops.

Since PyCode reflects every change in your external code, you will be informed every time your repository is more updated than the last time you edited your wiki page(s). This give you the possibility to keep up-to-date potential description to the embedded code.

More precisely, a banner notification for code out-of-date will appear only in the pages where the relative code is found and, if in one page there are more than one code block, only next to the code accused. Exclusively user with level permission greater than or equal to 2 ²⁾ can flush it away.

Just some screenshots to give you an overall idea of the final result.

Suppose to have a Python script called file.py hosted in a Bitbucket repository with name repo-test, in the master branch.

If you want to embed the entire script use the command:

<pycode https://bitbucket.org/Name/repo-test/src/master/file.py>

and this is what you get: Note, at the top of the page, the notification which points out to you that, since last time you edited the page, the code in the repository has changed.

You can also embed a portion of code between two line numbers, as described below, in Syntax.

Now you want to list all the methods of the Extra class:

<pycode https://bitbucket.org/Name/repo-test/src/master/file.py c Extra>

and the output will be: Each page will be created in the same namespace where this page lives.

Finally, you can populate each previous link with the relative Python code. For example, in the first link, we use the command:

<pycode https://bitbucket.org/Name/repo-test/src/master/file.py f __init__ Extra>

Note that we have specified from which class embed the __init__ method; if we had simply written:

<pycode https://bitbucket.org/Name/repo-test/src/master/file.py f __init__>

we would embed the first __init__ method found in the script.

Now we work on the repository and, for instance, we change the parameters of the class, we do some changes in def add, we rename def edt in def mod, we delete the def dlt method and add the def new method.

In your wiki, you will warned about this changes and the embedded code will not updated until you give your consent.

It's important to notice that a banner notification for a class can be flushed away in two manners:

1. clicking the button on the banner of the class: in this way all the code of the class will be updated so it will not necessary to visit each function;
2. clicking the button on the banner in each function of the class: in this way you have the possibility to keep up-to-date potential description to the code.

Last but not least, you can use the DokuWiki search engine to parse the code embedded.

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

Depending on where your Python script is hosted, the url of the source code, in short <src-url>, will be:

Then, the syntax is:

<pycode <src-url>>

<pycode <src-url> l <#>:<#>>

<pycode <src-url> l :<#>>

<pycode <src-url> l <#>:>

<pycode <src-url> l :>

<pycode <src-url> f <name-function>>

<pycode <src-url> f <name-function> <name-class>>

<pycode <src-url> c <name-class>>

For default, PyCode installs a menu wizard in your toolbar. If you don't want it you can disable this option in Configuration Manager > Pycode.

For default, PyCode doesn't cache the current page. On the one hand, doing this, you are sure that the code embedded reflects the changes in the repository. On the other hand, your browser has to download all the code (and the content of the page) every time you visit it.

If you want to reduce page load time you can disable this option, in Configuration Manager > Pycode, and put ~~NOCACHE~~ only at the beginning of those pages that you want to keep always up-to-date.

For default, PyCode doesn't add line numbers to your code but it is possible to activate this option from Configuration Manager > Pycode.

Moreover the line numbers are generated using the start and end line of the code as is in your repository.

Independently from the choose in the Configuration Manager, it is possible to specify whether show or hide the line numbers for each singular case adding:

<pycode ... -nums = 1>

<pycode ... -nums = 0>

For default, PyCode doesn't show any title for the code but it is possible to activate this option from Configuration Manager > Pycode. Here, you can select from:

Independently from the choose in the Configuration Manager, it is possible to specify whether show or hide a title for the code adding:

<pycode ... -title = "New title">

<pycode ... -title = "">

For default, PyCode doesn't show the methods and parent class's docstring, when you use the flag c, but it is possible to activate this option from Configuration Manager > Pycode.

It is available only when you list all the methods of a given class, and it is returned only the descriptive part of the docstring, if there is, so that the result is like a brief description.

For “descriptive part” is intended till the list of tags and since PyCode needs to know from which line they start, besides the PEP 257, only the following styles are supported:

• Google style:

  """This is Google style.
         
  More elaborate description.
  
  Last line that will be print.
   
  Args:
      param1: First param.
      param2: Second param.
  
  Returns:
      Description of what is returned.
  
  Raises:
      KeyError: Raises an exception.
  """

• Epytext style (for javadoc style remove :):

  """This is Epytext style
  
  More elaborate description.
  
  Last line that will be print.
  
  @param param1: First param.
  @param param2: Second param.
  @return: Description of what is returned.
  @raise keyError: Raises an exception.
  """

• reST style:

  """This is reST style.
  
  More elaborate description.
  
  Last line that will be print.
  
  :param param1: First param.
  :param param2: Second param.
  :returns: Description of what is returned.
  :raises keyError: Raises an exception.
  """

• NumPy style:

  """This is NumPy style.
  
  More elaborate description.
  
  Last line that will be print.
  
  Parameters
  ----------
  param1 : type
      First param.
  param2 : type
      Second param.
  
  Returns
  -------
  type
      Description of what is returned.
  
  Raises
  ------
  KeyError
      Raises an exception.
  """

Independently from the choose in the Configuration Manager, it is possible to specify whether show or hide the docstring for each singular case adding:

<pycode ... -docstr = 1>

<pycode ... -docstr = 0>

Symptom: PyCode can't distinguish the start an the end of a block of code in a Python script.

Possible solution: be sure that your code obeys the conventions for the Python code, defined in PEP 8, in particular remember to use 4 spaces per indentation level.

Symptom: PyCode doesn't update properly code out of date, even after its updating.

Possible solution: PyCode generates a folder called tmp where it saves a copy of the code embedded and which is used to determine how up to date is the code respect to the code hosted in the repository.

If there was a bug, most probably, this copy has been badly written and PyCode can't update the code.

In this case, when a new fixed version of PyCode is released, it's necessary to delete the tmp folder via Extension Manager > Uninstall > Install (Re-install doesn't delete it).

Bear in mind that doing this you lose track of which code is out of date.

Please, use the relative bug tracker or write here and then I will move there.
— Torpedo 2015/03/23 16:16

Let me know what do you think about this plugin and how can I improve its functionality.
— Torpedo 2015/03/23 16:16