====== PyCode Plugin ====== ---- plugin ---- description: Plugin to embed Python scripts (and others) hosted in a remote repository author : Torpedo email : dcstoyanov@gmail.com type : syntax lastupdate : 2019-11-25 compatible : 2014-09-29 "Hrun", 2015-08-10 "Detritus", 2016-06-26 "Elenor Of Tsort", 2017-02-19 "Frusterick Manners" depends : conflicts : similar : repo tags : !obsolete downloadurl: https://bitbucket.org/tormec/pycode/get/master.zip bugtracker : sourcerepo : https://bitbucket.org/tormec/pycode/src donationurl: screenshot_img : ---- ===== Description ===== 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 ((see [[wiki:syntax#Syntax Highlighting]])), 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 ((see [[:acl#Background Info]])) 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: and this is what you get: {{ https://bitbucket.org/tormec/pycode/downloads/script.png?nolink&recache }} 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 [[pycode#Syntax]]. Now you want to list all the methods of the ''Extra'' class: and the output will be: {{ https://bitbucket.org/tormec/pycode/downloads/class.png?nolink&recache }} 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: {{ https://bitbucket.org/tormec/pycode/downloads/method.png?nolink&recache }} Note that we have specified from which class embed the ''%%__init__%%'' method; if we had simply written: 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. {{ https://bitbucket.org/tormec/pycode/downloads/class-dif.png?nolink&recache }} It's important to notice that a banner notification for a class can be flushed away in two manners: - 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; - 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 ===== Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:plugin_installation_instructions|Plugin Installation Instructions]] on how to install plugins manually. ===== Syntax ===== Depending on where your Python script is hosted, the url of the source code, in short '''', will be: ^ Repository ^ '''' ^ | Bitbucket | ''%%https://bitbucket.org///src//%%'' | | GitHub | ''%%https://github.com///blob//%%'' | Then, the syntax is: ^ PyCode’s syntax |^ Output ^ | > || Embeds the entire script. | | l <#>:<#>> || Embeds the code from line ''<#>'' to line ''<#>''.\\ In particular: | | | l :<#>> | from the beginning to line ''<#>'' | | ::: | l <#>:> | from line ''<#>'' to the ending | | ::: | l :> | all the code (same effect as ''%%>%%'') . | | f > || Embeds the given function ''''. It doesn't mind if it belongs to a class or not since it embeds the first match. | | f > || Embeds the given method '''' from the specific class ''''. Useful if there are two methods, with the same name, in two different classes. | | c > || Lists all the methods of the given 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''. {{ https://bitbucket.org/tormec/pycode/downloads/wizard.png?nolink&recache }} ==== 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. {{ https://bitbucket.org/tormec/pycode/downloads/method-line-numbers.png?nolink&recache }} 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 ^ | | show line numbers | | | 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 | {{ https://bitbucket.org/tormec/pycode/downloads/method-title.png?nolink&recache }} 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 ^ | | add own 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 [[https://www.python.org/dev/peps/pep-0257/|PEP 257]], only the following styles are supported: * [[https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments|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. """ * [[http://epydoc.sourceforge.net/manual-epytext.html|Epytext]] style (for [[http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#format|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. """ * [[http://docutils.sourceforge.net/rst.html|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. """ * [[https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#a-guide-to-numpyscipy-documentation|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. """ {{ https://bitbucket.org/tormec/pycode/downloads/class-docstr.png?nolink&recache }} 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 ^ | | show docstring | | | 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 [[https://www.python.org/dev/peps/pep-0008/|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.