Target release9.0
Epic
Document status
DRAFT
Document owner

Julien Enselme

DesignerJulien Enselme
DevelopersJulien Enselme
QA
Julien Enselme

Goals

Provide support for the RestructuredText syntax. This will allow users to more easily write documentation for their Python scripts.

Background and strategic fit

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.

Assumptions

Requirements

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.

In RST files

#TitleUser StoryImportanceNotes
Provide syntax highlightingWhen the user opens or edits a RST file, all markup is correctly highlighted.Must HaveDone. 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
Provide spellcheckingWhen the user opens or edits words of the document are checked for spelling to avoid silly mistakes in the file.Must HaveDone.
Provide editing helpers
  1. When the user creates a title, the user uses a icon or a keyboard shortcut to make the current line a title (the alternative is to type the characters (=, -, ~, `, +, *) manually)
  2. When the user creates a sub list, the user needs to indent it to the proper level. The standard button and keyboard shortcut to indent/dedent text should work
Must Have
  • Complete title markup:
    • Inserts the tittle markup under the current line
    • Find keyboard shortcut
    • Create button
    • When pressed on a line that is a title:
      • If some symbols are missing, insert them
      • Switch between all available title levels
  • Provide indent/dedent helpers
  • Exclude directives from spellchecking
Provide hierarchical navigation with section titles in the navigatorWhen the user wants to navigate in a big file, the user can just use the navigator to avoid too much scrolling.Good to have 
Provide templates for directiveWhen the user inserts a directive, we provide a template that allows the user to easily edit the properties of this directive.Good to have 
Provide a list of inserted referencesWhen the user wants to navigate to a specific reference, the user can use the navigator to go to them.Good to have 
Provide a way to follow inserted referencesAllow the use to CTRL+Click on a reference to go to its definition.Good to haveFuture release. For it to work correctly, we need to scan all RST files of the project to find all the references.
Provide a previewAllow the user to preview the result of the document in HTML format.Good to haveFuture release.
  • Must be similar to what the Markdown plugin do
  • Should rely on rst2html to produce the output
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 table-insert in emacs: http://ergoemacs.org/emacs/emacs_table.html

In Python files

This will most likely be in a future release.

#TitleUser StoryImportanceNotes
Provide syntax highlightingWhen the user create a docstring identified by three quotes """, the text inside this string is highlighted depending on the RST rules.Good to have 
Provide spellcheckingWhen the user create a docstring identified by three quotes """, the text inside this string is given to the spellchecker for verification.Good to haveIs it possible to use the spellchecker within code files without interfering with the code?

User interaction and design

Questions

Below is a list of questions to be addressed as a result of this requirements document:

QuestionOutcome

Not Doing

Notes on the implementation

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.

How to add an element to the lexer

  1. Add a new token kind and token category in python.rst/src/org/netbeans/modules/python/rst/parser/RstTokenKind.java if 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:
    1. Add a RstTokenId in the RstLanguageHierarchy (in python.rst/src/org/netbeans/modules/python/rst/parser/RstLanguageHierarchy.java). The list is created in the init method.
    2. Add the proper colour in 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.
    3. Associate the new category to a human readable text in python.rst/src/org/netbeans/modules/python/rst/Bundle.properties. For instance, for the STRONG_EMPHASIS category, the association STRONG_EMPHASIS=Strong Emphasis. This text will be used in the options.
  2. Add the proper lexing logic in python.rst/src/org/netbeans/modules/python/rst/parser/RstLexer.java to create the token from the source code. Take inspiration from the existing methods to learn how to do that.

Credits

This page was imported from the nbpython wiki (https://nbpython.atlassian.net/wiki/spaces/N8/pages/25165831/RestructuredText+Support). Contributors: