DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:pycode

PyCode Plugin

Compatible with DokuWiki

  • 2017-02-19 "Frusterick Manners" yes
  • 2016-06-26 "Elenor Of Tsort" yes
  • 2015-08-10 "Detritus" yes
  • 2014-09-29 "Hrun" yes

plugin Plugin to embed a Python script (and other) hosted in a remote repository

Last updated on
2016-09-09
Provides
Syntax
Repository
Source

Description

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

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

The following table shows what you can do with PyCode:

Features Python script Other script language
Embed entire script.
Embed a portion of code between two line numbers.
Embed only a given function.
List all the methods of a given class and for each of them automatically create a link to a wiki page with the same name of the method.
Choose from which class embed a given method.

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 2) can flush it away.

Examples

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.

Installation

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.

Syntax

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

Repository <src-url>
Bitbucket https://bitbucket.org/<user>/<repo>/src/<branch>/<file>
GitHub https://github.com/<user>/<repo>/blob/<branch>/<file>

Then, the syntax is:

PyCode’s syntax Output
<pycode <src-url>>
Embeds the entire script.
<pycode <src-url> l <#>:<#>>
Embeds the code from line <#> to line <#>.
In particular:
<pycode <src-url> l :<#>>
from the beginning to line <#>
<pycode <src-url> l <#>:>
from line <#> to the ending
<pycode <src-url> l :>
all the code (same effect as <pycode <src-url>>) .
<pycode <src-url> f <name-function>>
Embeds the given function <name-function>. It doesn't mind if it belongs to a class or not since it embeds the first match.
<pycode <src-url> f <name-function> <name-class>>
Embeds the given method <name-function> from the specific class <name-class>. Useful if there are two methods, with the same name, in two different classes.
<pycode <src-url> c <name-class>>
Lists all the methods of the given class <name-class>. For each of them it is, automatically, created a link to a wiki page which has the same name of the method.

Configuration and Settings

Show shortcut buttons in the toolbar

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.

Disable the cache

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.

Show line numbers

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's option Description
<pycode ... -nums = 1>
show line numbers
<pycode ... -nums = 0>
hide line numbers

Show title for the code

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:

PyCode's option Description
none never show a title
file ⋅ class ⋅ def ⋅ #:# show a title of this form where class and def are applied only for Python script and are those, if there are, specified in the syntax
src-url ⋅ class ⋅ def ⋅ #:# show a title of this form where class and def are applied only for Python script and are those, if there are, specified in the syntax

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

PyCode's option Description
<pycode ... -title = "New title">
add own title
<pycode ... -title = "">
hide title

Show docstring

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's option Description
<pycode ... -docstr = 1>
show docstring
<pycode ... -docstr = 0>
hide docstring

Troubleshooting

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: after plugin upgrading, PyCode doesn't update properly code out of date.

Possible solution: PyCode generates a folder called tmp where it is saved 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, concerning how the code embedded has to be updated, it might happen that the copy of the code was badly written and PyCode can't update it.

Updating the plugin via Extension Manager > Re-install, tmp folder is not deleted.

When a new version, with the bug fixed, is released, you should Uninstal > Install the plugin in order to be sure that this folder is deleted.

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


Development

Known Bugs and Issues

Please, use the relative bug tracker or write here and then I will move there.

Torpedo 2015/03/23 16:16

ToDo/Wish List

Let me know what do you think about this plugin and how can I improve its functionality.

Torpedo 2015/03/23 16:16

plugin/pycode.txt · Last modified: 2017-03-09 17:37 by Aleksandr