Provide support for the RestructuredText syntax. This will allow users to more easily write documentation for their Python scripts.
RestructuredText (RST for short) is a markup format aimed to be as complete as LaTeX while being easier to write and parse. It is the format used by default to write docstrings in Python file. The full documentation of Python projects are also very often written using this language and generated in HTML/PDF/… with the sphinx-doc tool (http://www.sphinx-doc.org/en/stable/).
Currently, RST files are opened as Python files. Which means that the whole page is treated as a string (same yellow color for all text) and that the parser tries to validate it and thus reports syntax errors. This is bad for user experience and our users will most likely use another tool to edit their documentation files.
In order to improve NBPython, a basic support allowing the users to correctly edit RST files within NetBeans would be a good thing.
Once RST support is good enough in its own module, we should clean the source of the other modules to all RST related code. Furthermore, this code doesn't seem to be of any use at this time.
|1||Provide syntax highlighting||When the user opens or edits a RST file, all markup is correctly highlighted.||Must Have||Done. See the code here: https://bitbucket.org/Jenselme/nb-contrib/commits/branch/rst or the subject in the forum: http://forums.nbpython.org/viewtopic.php?f=14&t=139&p=723|
|2||Provide spellchecking||When the user opens or edits words of the document are checked for spelling to avoid silly mistakes in the file.||Must Have||Done.|
|3||Provide editing helpers||Must Have|
|4||Provide hierarchical navigation with section titles in the navigator||When the user wants to navigate in a big file, the user can just use the navigator to avoid too much scrolling.||Good to have|
|5||Provide templates for directive||When the user inserts a directive, we provide a template that allows the user to easily edit the properties of this directive.||Good to have|
|6||Provide a list of inserted references||When the user wants to navigate to a specific reference, the user can use the navigator to go to them.||Good to have|
|7||Provide a way to follow inserted references||Allow the use to CTRL+Click on a reference to go to its definition.||Good to have||Future release. For it to work correctly, we need to scan all RST files of the project to find all the references.|
|8||Provide a preview||Allow the user to preview the result of the document in HTML format.||Good to have||Future release.|
|9||Provide an helper to insert table|
When the user wants to insert a table, a very specific syntax needs to be respected. This syntax is tedious to fellow manually. The user will want a way to specify a number of line and column in order for NBPython to automatically insert the appropriate table.
When the user edits a table (adds/removes lines or columns, or adds text in a cell), the table must be automatically updated.
|Nice to have|
See https://rest-sphinx-memo.readthedocs.io/en/latest/ReST.html#tables to take a look at how tables needs to be formatted.
This could be similar to
This will most likely be in a future release.
|1||Provide syntax highlighting||When the user create a docstring identified by three quotes """, the text inside this string is highlighted depending on the RST rules.||Good to have|
|2||Provide spellchecking||When the user create a docstring identified by three quotes """, the text inside this string is given to the spellchecker for verification.||Good to have||Is it possible to use the spellchecker within code files without interfering with the code?|
Include any mockups, diagrams or visual designs relating to these requirements.
Below is a list of questions to be addressed as a result of this requirements document:
|(e.g. How we make users more aware of this feature?)||Communicate the decision reached|
RST support is handled in its own module:
python.rst. It was added thanks to the JavaCC Lexer Generator Integration Tutorial for the NetBeans Platform and JavaCC Parser Generator Integration Tutorial for the NetBeans Platform tutorials. Some adaptations were made in order to be consistent with the Python lexer and parser.
python.rst/src/org/netbeans/modules/python/rst/parser/RstTokenKind.javaif none of the existing correspond to what you need to add. The text of the category is important since it is this text that will be used to colourize the token. If you add a new kind or category, don't forget to:
python.rst/src/org/netbeans/modules/python/rst/parser/RstLanguageHierarchy.java). The list is created in the
python.rst/src/org/netbeans/modules/python/rst/FontAndColors.xml.You must use the name of the category to colourize the token. So all kinds in the same category are colourize the same way. A category can only appear once in this document.
python.rst/src/org/netbeans/modules/python/rst/Bundle.properties. For instance, for the
STRONG_EMPHASIScategory, the association
STRONG_EMPHASIS=Strong Emphasis. This text will be used in the options.
python.rst/src/org/netbeans/modules/python/rst/parser/RstLexer.javato create the token from the source code. Take inspiration from the existing methods to learn how to do that.