We assume, as you got here, that you have already a computer up and running being either a Liunx, MacOS or Windows machine as well as a working internet connection and some disk space available.
A 64 bit operating system is prefered running as much as possible the latest version of your preferred OS. This in any case is good practice to keep yur environment healthy and up to date.
The following sections describe what else you need for participating in the different efforts.
If you concentrate on documentation no additional hardware requrements exist. keep reading on but be reassured if you don’t feel comfortable with the following don’t worry we will find a way to have you contrbuting by other means. Just go to the contact us section and we will fina a way getting you on board or help you out getting things setup.
All documentation is done using reStructuredText for which you can find information here on the offical website: reStructuredText or here which is on the Sphinx document builder tool website which we discuss later on in this chapter. reStructuredText is a markdown type language for typesetting documents from websites to pdf or latex documents. Our Website is build upon this technology so you should make yourself familiar with this by looking through the links provided.
reStricturedText QuickReference Guide
Git & GitHub¶
You should have some knowledge about git and GitHub as we manage all of our doculentation (as well as the development) there. Depending on the editing platform of your choice you will get more or less support for this. You may want to install Github desktop or Sourcetree for getting a good idea on the state of the DCC-EX++ documentation github repository.
If you don’t have git installed its the right time to do this now from here
Download GitHub Desktop here
Download SourceTree here
You will need to choose a text editor, yes any text editor will do even the most simple one, but they will not provide editing help. We suggest you use VSC Visual Studio Code which provides additional components helping ou for editiing with syntax highlighting, text snippet and live preview of the rendering of the file as well as integration with github. Using a simple text editor will require you handling the git integration yourself.
Downlaod VSC here
and install the following extensions rst
The final website will be rendred from the rst text files using Sphinx which you need also to install with some options which you’ll find in the next paragraph
Sphinx is a transformation tool taking rst formatted documents and turns them into a static html website, pdf or LaTex documents.
Sphinx needs Python v3 So if you don’t have python installed so it’s time to do this now Install python how-to — to be done —
Once this is done you should also add the following extension to VSC — to be done — in order to enable the live preview of the documentation you write
— to be done : size , resolution etc to be added —
Graphs & Schemas¶
draw.io to keep compatibility not veryone has visio at hands. We suggest draw.io in order to keep the possibility for others to edit the document or work collaborativley on the same document. Export any schema or graph from draw.io in png format with settings if possible as outlined above.
— to be done graphviz to be added —
Work in progress
Once you have gone through all this head to the docuemntation section to see how it all works.
Additional hardware - Arduino / motorshield setup as you can find in :ref:
Work in progress