Page 1 of 1

What techno do you use to generate the documentation ?

Posted: Wed Jun 10, 2015 10:35 am
by MatthieuL
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

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

Posted: Wed Jun 10, 2015 6:23 pm
by MatthieuL
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...

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

Posted: Wed Jun 10, 2015 10:22 pm
by panik
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.

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

Posted: Thu Jun 11, 2015 2:37 pm
by MatthieuL
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.

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

Posted: Thu Jun 11, 2015 6:17 pm
by panik
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.

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

Posted: Fri Jun 12, 2015 7:21 am
by ghans
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

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

Posted: Fri Jun 12, 2015 9:31 am
by ben_nuttall
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.

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

Posted: Fri Jun 12, 2015 9:55 am
by ghans
Thanks for the followup . The articles at opensource.com are interesting too.

ghans

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

Posted: Fri Jun 12, 2015 10:20 am
by MatthieuL
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

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

Posted: Fri Jun 12, 2015 10:28 am
by DougieLawson
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.

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

Posted: Fri Jun 12, 2015 10:48 am
by panik
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/

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

Posted: Sun Mar 27, 2016 10:00 pm
by mc007ibi
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...