MatthieuL
Posts: 4
Joined: Wed Jun 10, 2015 10:12 am

What techno do you use to generate the documentation ?

Wed Jun 10, 2015 10:35 am

Hi !

I really like the way you handle documentation using markdown pages (https://github.com/raspberrypi/documentation/) which are then nicely displayed on the main website:
https://www.raspberrypi.org/documentation/

On our project, we also have markdown documentation hosted on github but we do not have the nice HTML/CSS template you have to render static documentation pages.

So I would like to know more about the techno your are using ?

Thanks !

Matthieu

MatthieuL
Posts: 4
Joined: Wed Jun 10, 2015 10:12 am

Re: What techno do you use to generate the documentation ?

Wed Jun 10, 2015 6:23 pm

So I continue looking for hints in the source code about the way you do.

It seems there is a wordpress somewhere and the few ruby code on the repository transform markdown syntax into HTML one.

I just need to find the black matter which link the 2...

User avatar
panik
Posts: 369
Joined: Fri Sep 23, 2011 12:29 pm
Location: Netherlands

Re: What techno do you use to generate the documentation ?

Wed Jun 10, 2015 10:22 pm

Have a look at Parsedown: http://parsedown.org/

Code: Select all

<?php
include("Parsedown.php");

$markdown = file_get_contents('path/to/file.md');
$markup = Parsedown::instance()->text($markdown);
echo $markup;
?>
The css could be anything from anywhere that styles basic html.
Microcontroller addon boards and software for Raspberry Pi A+/B+/Pi2:
- ARMinARM: ARM Cortex-M3 (STM32)
- AVRPi: ATmega32U4 & ATmega328 ("Arduino")
http://www.onandoffables.com

MatthieuL
Posts: 4
Joined: Wed Jun 10, 2015 10:12 am

Re: What techno do you use to generate the documentation ?

Thu Jun 11, 2015 2:37 pm

Thanks for the link, I did not know this tool.

Yet I'm not sure this is used on the raspberry pi documentation, or I do not undestand why there is a gemfile and a rakefile on the github repo.
It seems there is something build on the github server (travis config) then something get the HTML and display it with a template on the main website.

User avatar
panik
Posts: 369
Joined: Fri Sep 23, 2011 12:29 pm
Location: Netherlands

Re: What techno do you use to generate the documentation ?

Thu Jun 11, 2015 6:17 pm

It'd be interesting to know what those files are about. They possibly have something to do with automatically updating the website after a commit/push. Not sure.

I'm using a simple bash script to wget the raw .md files from github to an offline directory, renaming them appropriately and then ftp it to the live website. My workflow is:

Code: Select all

git push origin master
./updatewebsite.sh
Lo-tech, but efficient.

Obviously, ftp straight from the source directory works too, but I'm too lazy for that. Too many files and names to remember.
Microcontroller addon boards and software for Raspberry Pi A+/B+/Pi2:
- ARMinARM: ARM Cortex-M3 (STM32)
- AVRPi: ATmega32U4 & ATmega328 ("Arduino")
http://www.onandoffables.com

ghans
Posts: 7883
Joined: Mon Dec 12, 2011 8:30 pm
Location: Germany

Re: What techno do you use to generate the documentation ?

Fri Jun 12, 2015 7:21 am

Travis is instructed to use the Rakefile to render and test the Markdown. The renderer is redcarpet.
How the result gets onto the official website is a mystery to me too.

ghans
• Don't like the board ? Missing features ? Change to the prosilver theme ! You can find it in your settings.
• Don't like to search the forum BEFORE posting 'cos it's useless ? Try googling : yoursearchtermshere site:raspberrypi.org

User avatar
ben_nuttall
Posts: 235
Joined: Sun Aug 19, 2012 11:19 am
Location: Cambridgeshire, UK
Contact: Website Twitter

Re: What techno do you use to generate the documentation ?

Fri Jun 12, 2015 9:31 am

MatthieuL wrote:Yet I'm not sure this is used on the raspberry pi documentation
I can confirm it does use Parsedown.

I have an .htaccess file that redirects all requests into index.php, which looks up the request inside the docs folder (a clone of the repo), and renders it in a template to make it look like the rest of the website.

The learning resources work in the same way, but with a much more bespoke template. Depending on the request, either a cover page, requirements page, worksheet, etc. is rendered. These templates pull in bits of other files, and use YAML files for other config.

I wrote about the non-technical side of this - why we do it, etc, at opensource.com
MatthieuL wrote:or I do not undestand why there is a gemfile and a rakefile on the github repo.
It seems there is something build on the github server (travis config) then something get the HTML and display it with a template on the main website.
The Travis CI stuff is nothing to do with the markdown->HTML parsing. It's just a continuous integration build that tests the markdown is ok, no broken links, etc.
Former RPF staff. Author of gpiozero and creator of piwheels.

ghans
Posts: 7883
Joined: Mon Dec 12, 2011 8:30 pm
Location: Germany

Re: What techno do you use to generate the documentation ?

Fri Jun 12, 2015 9:55 am

Thanks for the followup . The articles at opensource.com are interesting too.

ghans
• Don't like the board ? Missing features ? Change to the prosilver theme ! You can find it in your settings.
• Don't like to search the forum BEFORE posting 'cos it's useless ? Try googling : yoursearchtermshere site:raspberrypi.org

MatthieuL
Posts: 4
Joined: Wed Jun 10, 2015 10:12 am

Re: What techno do you use to generate the documentation ?

Fri Jun 12, 2015 10:20 am

ben_nuttall wrote: I have an .htaccess file that redirects all requests into index.php, which looks up the request inside the docs folder (a clone of the repo), and renders it in a template to make it look like the rest of the website.
Thanks ben, it is more clear now.
However, for a non-web-dev like me, it seems there is a lot of step before making all this work correctly.

Does your website is somehow "open", i.e. can you share the code you have so we can see how it is actually done ?

- the htaccess redierctions
- index.php
- the template

User avatar
DougieLawson
Posts: 40203
Joined: Sun Jun 16, 2013 11:19 pm
Location: A small cave in deepest darkest Basingstoke, UK
Contact: Website Twitter

Re: What techno do you use to generate the documentation ?

Fri Jun 12, 2015 10:28 am

ben_nuttall wrote: I can confirm it does use Parsedown.
[snip]
I wrote about the non-technical side of this - why we do it, etc, at opensource.com
That's for sharing that. And thanks to panik for the link to "Parsedown", I've snagged a copy of that as being able to test my markdown before I publish it on Github has lots of value.
Criticising any questions is banned on this forum.

Any DMs sent on Twitter will be answered next month.
All fake doctors are on my foes list.

Note: Any requirement to use a crystal ball or mind reading will result in me ignoring your question.

User avatar
panik
Posts: 369
Joined: Fri Sep 23, 2011 12:29 pm
Location: Netherlands

Re: What techno do you use to generate the documentation ?

Fri Jun 12, 2015 10:48 am

DougieLawson wrote:That's for sharing that. And thanks to panik for the link to "Parsedown", I've snagged a copy of that as being able to test my markdown before I publish it on Github has lots of value.
It might be noteworthy that github uses a 'github flavored markdown' which Parsedown renders correctly.
https://help.github.com/articles/github ... -markdown/
Microcontroller addon boards and software for Raspberry Pi A+/B+/Pi2:
- ARMinARM: ARM Cortex-M3 (STM32)
- AVRPi: ATmega32U4 & ATmega328 ("Arduino")
http://www.onandoffables.com

User avatar
mc007ibi
Posts: 66
Joined: Wed Dec 16, 2015 7:36 pm
Location: barcelona

Re: What techno do you use to generate the documentation ?

Sun Mar 27, 2016 10:00 pm

I am using markdown with daux.io, it takes a directory filled with markdown files and then creates a boostrap3 based
page, it creates offline docs too. there are others too...

Return to “General discussion”