This is a standard for contributing to this documentation (SeLite.github.io). Read AboutDocumentation first.
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).
# Heading... #).
<, >), then specify its ID on the next line in form
.mdfiles. Such comments work well online, but not with Markdown Viewer in Firefox.
bundle exec jekyll serve. The default port is 4000 (the local website at http://localhost:4000). Alternatively pass a port, e.g.
bundle exec jekyll serve --port 8000.
gem install link-checkerand
check-links _site(not maintained since v. 0.7.2, Oct 2012; it reports broken external links but not broken local links). Don’t use
html-proofergem and its
htmlproofcommand (since it doesn’t like GitHub-based relative links).
gem install jekyll --pre):
sudo cpan -i Config::General Net::IP CSS::DOM
tar xvzf W3C-LinkChecker-4.81.tar.gz; cd W3C-LinkChecker-4.81; perl Makefile.PL; make; sudo make install
checklink --quiet --location http://localhost:4000/ http://localhost:4000/
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).
.pngwell - the quality was low.
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.
Don’t use Kramdown-specific header IDs, since they don’t work in Markdown Viewer in Firefox..
GitHub doesn’t serve raw versions of most file types with their MIME, except for images.
.htmlfiles (but not for processing them programatically). It fetches the latest commit of that file. Therefore you don’t have to update those links (unless you move the file).
.js), and for processing
.htmlfiles programatically, use rawgit.com
'blocked due to mime type mismatch').
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 . –>