RST files have an *.rst extension, and GitHub does a great job of rendering them. They use a markup that means the source file is very readable. Look at one of the RST files in the source directory. Click the Raw button to view the VST file.
The links will help get you up to speed with editing RST files:
If you are writing a new article for the academy or doing a heavy edit involving adding links etc., it is best to clone this repository and build and test the updated version of the Stratis Academy locally.
Installing Sphinx using the resources available here meant a few queries in Stack Exchange etc. Therefore, I have documented the process for the Mac including building the Academy, which should smooth out the installation process. If anyone completes this for Windows, please update this document detailing the process.
- Python must be installed. Currenly, Macs seem to be shipping with version 2.7. That is not the latest version (which is 3.7) but it worked without the need for an upgrade.
- Install pip, which is a package management system for Python. To do this, start a bash shell (terminal) and enter the following:
sudo easy_install pip. The sudo program will ask for your password before proceeding. - Install Sphinx by entering the following:
pip install Sphinx –-user. Ideally, you should now see this:
However, it will (most likely) complain some packages it relies on, such as tornado and nose are not installed. - If required, use sudo to install the missing packages:
sudo easy_install tornado,sudo easy_install nose. Then enterpip install Sphinx --useragain and you should see the requirement has been satisfied for all packages. - The sphinx-build command is now in
$HOME/Library/Python/2.7/bin. If you are using the up-to-date version of python, the version number will be different. It is best to add this path to the $PATH enviromental variable. To do this, add the follwing line:export PATH="$HOME/Library/Python/2.7/bin:$PATH"to your$HOME/.bash_profilefile. Note that this file is hidden. - Clone this Documentation repository after first creating a folder in which hold the clone. You will see why in the next step.
- In the "root" of the Documentation repository, enter
make html. You should see something like this:
The output be in a builddirectory at the same level as your Documentation repository. Thebuilddirectory position is to stop the output getting mixed up with the source. - In your browser, now open
build/html/index.htmlusing the file protocol. From here, you should be able to navigate around your updated version of the academy. - When you are happy with your updates, submit a pull request.
As an alternative to using the file protocol to view the academy, Python provides a quick way to run a local Http Server. Start a bash shell (terminal) and navigate to build/html from within the folder you created to hold the Documentation repository clone.
If you are using version 2.7, enter:
python -m SimpleHTTPServer 8000
If you are using version 3.x, enter:
python -m http.server
Haven't tried the 3.x command... Once the local Http Server is running, you should see something like this:
Navigate to http://localhost:8000 and you should see the your updated version of the academy.
The pages listed here contain ideas for articles for each category. Currently, the plan is add more articles on the full node, and the ideas for this so far are listed here:
This will give the full node category a "cookbook" type approach, which I think will work well under the current circumstances. I am thinking that when you look down the full node contents, you will see engaging questions like "How do you interpret the full node output?" Please feel free to add more ideas to the list (and start another list for smart contracts etc.).
Regarding links, Sphinx can be a a bit cryptic on the subject of internal links. If offers a number of options but, at least on the subject of anchors, I had to dig around for info:
###Link to a header in the same file and use the header text
Take the following header:
If you are OK with the link text being the same as the header text:
This is how to link to My header_.
###Link to something other than a header in the same file
The next thing you might want to do is create an link to an image, code example etc. The text in the link could be anything. To do this, create a label above the image or whatever to create an anchor:
.. _some_figure:
.. image:: stars.jpg :width: 200px :align: center :height: 100px :alt: alternate text
Then link like this:
Please refer to the :ref:previous figure <some_figure>.
Remember to always leave a gap on one line between the label and what you want to link to; otherwise you get a warning.
###Link to a header in the same file but don't use the header text