This is a standard for contributing to this documentation (SeLite.github.io). Read AboutDocumentation first.

Format

Having documentation in one large piece would make its structure too rigid. Maintenance and online navigation would be impractical. Instead, it’s split into small pages. Therefore it doesn’t exist in other formats. Offline viewing is easy in Firefox:

Run Jekyll locally.

SeLite doesn’t use GitHub Wiki, which doesn’t utilise screen well, especially on mobile devices. (E.g. its sidebar has a wide mandatory part).

Maintaining the documentation

Drawn diagrams

Don’t use UML tools, as they are more restrictive and less efficient.

Draw diagrams in LibreOffice/OpenOffice and save them as .odg. Then Edit > Select All; File > Export (export the selection, rather than the whole drawing area). Export as a .png, not interlaced, with lowest compression. Then commit both .odg and .png to git. In documentation use URLs of ‘Raw’ images from git (e.g. selite/diagrams/ > navigate to .png file > get URL of ‘Raw’ button).

Versions of LibreOffice

Please

Textual object diagrams

Object Diagrams draw ownership/reference relationships between objects, fields and functions. They usually don’t necessarily describe class inheritance (which is clear from the source and from API).

Text diagrams don’t need to be esthetic, but clear and easy to edit - so you can quickly update them whenever you change the relevant code. They are in plain text, with <, >, ^, v for connections. The diagrams look like this:

Example                                     Description

ObjectConstructorName                       Full name of the class - i.e. the constructor function of the object.
Below the object constructor name are object fields. Indent them with two spaces.

.fieldName                                  Field with a fixed (known) name. Prefix it with a dot.

[ index description or expression ]         Dynamic field name.

[ ObjectConstructorName.SECRET_FIELD_NAME ] Field with a fixed name, not referred to via a string/numeric literal across the code,
but rather as a value of a defined constant.

Headers IDs must be the same as their text

Don’t use Kramdown-specific header IDs, since they don’t work in Markdown Viewer in Firefox..

Raw content from GitHub

GitHub doesn’t serve raw versions of most file types with their MIME, except for images.

Generating cdn.rawgit.com-based URLs

The most difficult part is to locate the ‘Raw’ link (on GitHub) for a chosen commit.

The URL will start with https://raw.githubusercontent.com/. Copy the URL. Paste it at https://rawgit.com. Take the url starting with https://cdn.rawgit.com.

For example, the ‘Rw’ URL is_https://raw.githubusercontent.com/selite/selite/XYZ…/<component’s-name>/src/chrome/…_ Then append the path part of that URL to https://cdn.rawgit.com/, i.e. https://cdn.rawgit.com/selite/selite/XYZ…/<component’s-name>/src/chrome/…

Apply similar steps to SelBlocksGlobal. <!–TODO Ubuntu 16.04 apt-get install ruby ruby-dev zlib1g-dev gem install github-pages

npm config set proxy http://your-proxy:port npm i -g jsdoc vi /usr/local/bin/jsdoc # -> change ‘node’ to ‘nodejs’ on the first line, because Ubuntu uses nodejs instead of node

cd docs git checkout gh-pages echo nbproject ».gitignore echo .gitignore ».gitignore

git branch gh-pages git checkout gh-pages jsdoc -r ../SeLite ../SelBlocksGlobal -d . #jsdoc –readme ./path/to/README-for-docs.md -r ../selite ../sel-blocks-global -d . git add * git commit -a -m Autogenerated git push origin gh-pages

git checkout master git branch -D gh-pages git push origin :gh-pages

#For jsdoc-baseline npm install -g js-beautify OR pip install jsbeautifier

underscore-contrib jsdoc –template ../jsdoc-baseline -r ../SeLite ../SelBlocksGlobal -d . –>