[Documentation] software proposal for Armbian wiki

[wildcat_paris]

I am opening a thread to pick a wiki software for Armbian documentation (or any software to help documentation building)

 

feel free to propose a solution. Thanks.

[wildcat_paris]

I would propose MoinMoin

https://en.wikipedia.org/wiki/MoinMoin

 

More or less, the Armbian forum message layout uses the same concepts

 

I have been using this along CAcert.org former project

https://wiki.cacert.org/

 

yes we (CAcert former crew) had trouble with XSS attacks. better not to use plugins.

https://moinmo.in/SecurityFixes

[wildcat_paris]

I have seen the wiki option on github

[Tido]

I like it the way C.H.I.P does it http://docs.getchip.com/chip.html

I cannot remember which markup language they are using ... something with M ?

 

Ah, and it should be possible to export article or pages to PDF.

 

Licence like: Creative Commons

[zador.blood.stained]

I like it the way C.H.I.P does it http://docs.getchip.com/chip.html

I cannot remember which markup language they are using ... something with M ?

Looks like Markdown to me - same that we use now and that can be used on GitHub based wikis.

[Tido]

 

Looks like Markdown to me - same that we use now and that can be used on GitHub based wikis.

Ahh exactly, I knew it was an M :-)

 

And Markdown can export to PDF, now I don't know about the possibilities of the GitHub Wiki.

To create one:

Go to the repository, there is a settings link (in the same line as it says <>code), within those settings you can click it:

GitHub Wikis is a simple way to let others contribute content. Any GitHub user can create and edit pages to use for documentation, examples, support, or anything you wish.

 

So it looks to me it is a Wiki per Repository.

[lanefu]

I'm a big fan of markdown-based solutions.

 

I moved my team from a wiki to markdown + mkdocs and have great success.

 

here's a few bullet points (i recognize some of these may be redundant to other posts in the forum)

 

* typically content renders nicely out of the box with modern version control front ends such as github, bitbucket, gitlab

* markdown's popularity lowers barrier to entry across masses

* text file nature easy for *nix users and developers to quickly update docs while coding from their favorite editor or IDE

* file ÷ git commit process makes writing the doc feel more deliberate / focused because process is the same as commiting code. ive experienced documentation quality go up because of it

* output in multiple formats via post processing.

 

 

as an example my doc repo has a git hook that executes mkdocs on post commit. my internal documentation is automatically updated with searchable documentation.

[Igor]

How are you producing PDFs? This is my way:

apt-get install pandoc nbibtex texlive-latex-base texlive-latex-recommended texlive-latex-extra preview-latex-style dvipng texlive-fonts-recommended
pandoc input.md --standalone -o output.pdf -V geometry:"top=2.54cm, bottom=2.54cm, left=3.17cm, right=3.17cm" -V geometry:paperwidth=21cm -V geometry:paperheight=29.7cm

Probably better way exist.

[Igor]

I found and apply "markdown-pdf" tool. Lightweight and looks good enough out of the box I would say.

Preview result in attachment - without any corrections or order.

Armbian_5.14_documentations.pdf

[zador.blood.stained]

Noticed following problems:

• Links need some work
• Inline code (`code`) needs another color for highlighting
• Youtube video block needs to be removed or converted to link
• Line wraps in code blocks are not perfect
• Whole document needs index (hope this tool does support that)
• Page numbers may be good too

[Tido]

Exactly, it should work out of box.

235KB for 36 pages is a good result, one font style (DejaVu) even with some SDcard pictures.

 

The long "Release history" should be at the end and I miss a "table of contents" like you can see in this Wiki or like mentioned above at C.H.I.P.

[tkaiser]

 

Noticed following problems:

• Links need some work
• Inline code (`code`) needs another color for highlighting
• Youtube video block needs to be removed or converted to link
• Line wraps in code blocks are not perfect
• Whole document needs index (hope this tool does support that)
• Page numbers may be good too

 

I agree. And had a look how we produce documentation. It's basically Textile or Markdown that will converted to HTML and then using htmldoc an indexed PDF with page numbers and clickable TOC gets created. The final step is

HTMLDOCOptions="--embedfonts --headfootfont helvetica-oblique --headfootsize 7 --header ..c --tocheader . --firstpage c1 --quiet --browserwidth 900 --pagemode outline --fontsize 8 --format pdf14 --bodyfont helvetica --bottom 1cm --pagelayout single --left 2.5cm --right 2cm --top 1.7cm --linkstyle plain --linkcolor blue --textcolor black --bodycolor white --links --size 148x210mm --landscape --compression=9 --jpeg=95 --toctitle Inhaltsverzeichnis --charset iso-8859-1"
HTMLFiles="/Users/tk/Documents/Projekte/Templates/Doku/00_Vorwort.html $(ls "$1/"*.html)"
/usr/local/bin/htmldoc ${HTMLDOCOptions} --numbered --toclevels 4 --book --titlefile "${TitleFile}" -f "$1/${Title}.pdf" ${HTMLFiles}

From MD to HTML probably with http://www.mkdocs.orgas @lanefu suggested? We also need to use numeric prefixes for the various .md files in our documentation directory.

[lanefu]

I found and apply "markdown-pdf" tool. Lightweight and looks good enough out of the box I would say.

Preview result in attachment - without any corrections or order.

that output is totally good enough!

 

To me the value of PDF documentation is for treating it as e-reading for ones platform of choice (or wasting paper) look just fine on mobile. ... requirement met

 

HTML docs value is for people in their standard project hacking scenarios where browser is king.

 

Sent from my SM-G920V using Tapatalk

[Igor]

Usage: markdown-pdf [options] <markdown-file-path>

  Options:

    -h, --help                               output usage information
    -V, --version                            output the version number
    <markdown-file-path>                     Path of the markdown file to convert
    -c, --cwd [path]                         Current working directory
    -p, --phantom-path [path]                Path to phantom binary
    -h, --runnings-path [path]               Path to runnings (header, footer)
    -s, --css-path [path]                    Path to custom CSS file
    -z, --highlight-css-path [path]          Path to custom highlight-CSS file
    -m, --remarkable-options [json-options]  Options to pass to remarkable
    -f, --paper-format [format]              "A3", "A4", "A5", "Legal", "Letter" or "Tabloid"
    -r, --paper-orientation [orientation]    "portrait" or "landscape"
    -b, --paper-border [measurement]         Supported dimension units are: "mm", "cm", "in", "px"
    -d, --render-delay [millis]              Delay before rendering the PDF
    -t, --load-timeout [millis]              Timeout before the page is rendered in case `page.onLoadFinished` isn't fired
    -o, --out [path]                         Path of where to save the PDF

I am still working on but according to now:

- better code highlighting can be done with .css, since it's converted to HTML and than to PDF

- YouTube should be converted to link

- Line wraps. Probably doable with .css

- clickable TOC, have to study but I think not possible out of the box

- page numbers, currently no idea

 

Numeric prefixes, yes. I am currently creating 01-cover-page.md

 

Edit:

I am already happy even with this. One searchable document with simple TOC at start. It's also possible to create two main documents or one divided into two major section, user / geek and with different background color. That's possible to do fairly easy.

 

Edit: some structural changes

Armbian_5.14_documentations.pdf

Edited June 24, 2016 by Igor
add new pdf

[tkaiser]

Hmm... quick test using MkDocs and htmldoc (without adjusting anything):

for i in main* ; do NewSite="http://127.0.0.1:8000/$(echo $i | sed 's/\.md/\//')"; Sites="${Sites}${NewSite} "; done
htmldoc ${HTMLDOCOptions} --book --numbered --toclevels 3 -f ../armbian-userdoc.pdf ${Sites}

Someone familiar with MkDocs could tweak HTML/CSS quickly and adding title page (with logo) and headers/footers in htmldoc is also easy: http://kaiser-edv.de/tmp/HbBtyV/armbian-userdoc.pdf  (different structure levels ruin the 'book/TOC structure')

[Igor]

This looks like a serious tool.

 

I won't proceed in fine tuning on any of method, so it's free to claim.

[tkaiser]

This looks like a serious tool.

 

I won't proceed in fine tuning on any of method, so it's free to claim.

 

 

Well, I just looked into MkDocs a little more (10 minutes). It seems all that's needed is an additional index.md that defines the final structure, eg.

Site_name: Armbian ${temprevision}
pages:
- User FAQ: main-01-user-faq.md
- Enabling Hardware Features: main-02-Enabling_hardware_features.md
- H3 Mini FAQ: main-03-H3_mini_faq.md
- Geek FAQ: main-04-geek-faq.md
- FEL Boot guide: main-05-fel-boot.md
- Version history: main-06-logbook.md

(so no need for numerical prefixes since order can be defined here). I used also the wrong mode before (webserver on 127.0.0.1) but mkdocs can also produce a set of temporary static HTML files (which can then be adjusted easily, eg. making the youtube links work). If the search stuff will be deactivated and headers/footers in MkDocs then the raw material to be fed into htmldoc is already perfect.

 

With htmldoc you then get clickable TOC generation, headers/footers, page numbers and the like for free (this tool is from Mike Sweet, main author of CUPS, so generated PDF is also not that dodgy as that produced by most other tools). I think it's pretty easy for someone familiar with MkDocs to provide perfect HTML (integrated into github workflow so that documentation commits trigger a new PDF manual version), piping that into htmldoc is easy too. The only 'real task' would be adjusting header levels in our various docs so that a nice 'PDF book' gets created in the end.

 

That being said I won't look into this any more also. Any volunteers?

 

Edit: IMO the final goal if MkDocs will be used together with htmldoc would be two sets of documentation. MkDocs should produce a set of static HTML files (generation triggered through github commits) and these should also be rendered to a nice looking PDF 'manual'. IMO we still suck when it's about documentation, especially the 'why do users do NOT look into available docs' part.

[lanefu]

 

That being said I won't look into this any more also. Any volunteers?

 

Edit: IMO the final goal if MkDocs will be used together with htmldoc would be two sets of documentation. MkDocs should produce a set of static HTML files (generation triggered through github commits) and these should also be rendered to a nice looking PDF 'manual'. IMO we still suck when it's about documentation, especially the 'why do users do NOT look into available docs' part.

 

 

Still grokking big picture -- interest piqued.   

[Tido]

I can take a look at it.

@tk, guide the user to the manual /wiki before answer it in the forum.
Kind if easy, but u must be follow such a 'rule'

 

Edit Tido:

Kind of easy, but u must follow such a 'rule'

 

 

 

@WP, thanks for edit - bloody cell phone :-)

Edited June 26, 2016 by Tido
no tk bashing please :) at least, only once a day to keep the doctor away ;)

[wildcat_paris]

Hmm... quick test using MkDocs and htmldoc (without adjusting anything):

for i in main* ; do NewSite="http://127.0.0.1:8000/$(echo $i | sed 's/\.md/\//')"; Sites="${Sites}${NewSite} "; done
htmldoc ${HTMLDOCOptions} --book --numbered --toclevels 3 -f ../armbian-userdoc.pdf ${Sites}

Someone familiar with MkDocs could tweak HTML/CSS quickly and adding title page (with logo) and headers/footers in htmldoc is also easy: http://kaiser-edv.de/tmp/HbBtyV/armbian-userdoc.pdf  (different structure levels ruin the 'book/TOC structure')

 

markdown-pdf looks nice but missing the htmldoc TOC structure that is very useful to RTFM

[lanefu]

okay.. I'll volunteer now...based on my understanding of this thread

 

A quick recap and some strategic questions about the direction we're heading.

 

Documentation will be provided in the following formats:

• HTML / HTML Site w/ clean url ex: http://armbian.com/documentation/userdocs
• PDF (style of user manual)
• MD (github convenience  -- automatically renders individual files)

Following tools will be used:

• mkdocs
• htmldoc

Behavioral Requirements

• Functional TOC in PDF
• Search (for html site?)

Questions:

• Should we move documentation to a separate repo and update lib/documentation to be a git submodule?
• Where should the documentation output be stored (html/pdf)?
• Should documentation resources automatically be updated after every documentation commit?

[miked]

I did a bit of experimentation and have the following suggestions:

 

1. On http://www.armbian.com/change "Getting Started" to "Documentation". Currently all documentation is under "getting started" which isn't an intuitive place to look for advanced stuff.

However since you want a clear "where to start" sign that stands out to new visitors, we could have a prominent "Getting Started: Everything you need to get Armbian up and running" icon/link/banner stickied near the top of the Home page (and maybe Downloads page if people are directly linked there from external sites). It should take you to a documentation page that starts with an outline (with links) of the main steps a complete novice would take.

 

2. If the html docs are going to be mainly mkdocs output with some post-processing, I would try to put the output underneath the Armbian nav bar, using a theme that has the Documentation navigation on a left sidebar to avoid crowding the top. Theme readthedocs does this. It should be possible to use html <embed> to shove the mkdocs webpage into the Armbian web page. Unless someone really wants to tweak the theme and process the output to look perfect, maybe as little as changing the theme's colors will be enough to make it look good.

 

Edit: That is, either you could let mkdocs use the whole browser window, which is not ideal because it looks like the documentation is a different site. Or leave mkdocs output as a full webpage and embed it, which I think would be easiest to try. Or process the output a lot so that you combine the Armbian page and the mkdocs output into one generated page, which should be more work but give you more control.

[Igor]

Few my ideas.

 

Should we move documentation to a separate repo and update lib/documentation to be a git submodule?

 

I think no need for this. I expect lot's of changes now, since we need to add few things and apply better structure to what's already done.

 

Let's see what do we have now:

 

"user faq" - This suppose to be "Getting Started: Everything you need to get Armbian up and running". It's close to that, except some things might be too advanced for novice user.

"enabling HW features" - is little more than this, but not many things present at the moment. Here we could add (move from) most important things: connecting spi / i2c displays, sensors, ... The main question remain "how far" should we go with all this?

"h3_mini_faq" - logbook and user faq only for H3. How to deal with per board stuff? Generally.

"geek faq" - how to deal with tools. We need 2-3 script user review to be done and merged into this documentation (can be claimed for board). Our / coder POW is not the best to write such manual. Basically one must start from scratch, test all functions and write down experiences, written in manual/howto style.

"fel-boot" - features within tools. The same. Someone from outside should review / rewrite the docs.

 

Where should the documentation output be stored (html/pdf)?

 

Current situation: docs sources are .md and they are rendered to .html within blog and there we can set permanent links per documents. This part is not that bad after all. "Getting started" and "Basic" is the same page just in case someone does not understand it properly. Next doc is "Building" aka "geek manual" and a log book.

 

One idea is, to merge all those sections into one .pdf file "Armbian handbook". First part basic stuff, than few howtos and building howtos, walk trough and perhaps logbook at the end.

 

Should documentation resources automatically be updated after every documentation commit?

Not necessarily but we can do that quickly in the future if needed. 
 

 Downloads page if people are directly linked there from external sites

One more exposed link on the download page would help, agree. Elsewhere is not critical since the page offers pretty strait links: download, docs, sources and forum. I think main problem is that we don't have proper docs internal organization, few things are doubled, build script needs much more explanation, examples, ... where to put log of changes? We even have separate, more detailed for H3. 

[Tido]

• Should we move documentation to a separate repo and update lib/documentation to be a git submodule?

 If documentation is a GitHub Repo, then everybody can send a pull request /or leave a comment.

Wouldn't this improve the documentation ?

 

I would try to put the output underneath the Armbian nav bar, using a theme that has the Documentation navigation on a left sidebar to avoid crowding the top. Theme readthedocs does this.

 This would offer the possibility of a nice structured HTML manual

 

 

"h3_mini_faq" - logbook and user faq only for H3. How to deal with per board stuff? Generally.

I wrote this already above:

To create one:

Go to the repository, there is a settings link (in the same line as it says <>code), within those settings you can click it:

GitHub Wikis is a simple way to let others contribute content. Any GitHub user can create and edit pages to use for documentation, examples, support, or anything you wish.

So it looks to me it is a Wiki per Repository.

This can be linked out of the HTML manual if requested.

 

"geek faq" - how to deal with tools. We need 2-3 script user review to be done and merged into this documentation

I am sorry, I don't understant the idea /intention - maybe it's just me

[Igor]

I am sorry, I don't understand the idea /intention - maybe it's just me

 

To get a different view(s), from different user perspective, summary of that. Tool makers can easily forget to mention or describe some functions.

[tkaiser]

The one problem I had with a github wiki was how to access the raw contents? But as usual it's quite easy. Editing wiki pages creates revisions and raw .md can be obtained in an automated fashion:

 

The latest revision of https://github.com/ThomasKaiser/lib/wiki/01-User-documentation for example is always accessible as: https://raw.github.com/wiki/ThomasKaiser/lib/01-User-documentation.md

 

The whole wiki is just a git repo in itself so cloning it locally is also possible: https://github.com/ThomasKaiser/lib.wiki.git

[lanefu]

The one problem I had with a github wiki was how to access the raw contents? But as usual it's quite easy. Editing wiki pages creates revisions and raw .md can be obtained in an automated fashion:

 

The latest revision of https://github.com/ThomasKaiser/lib/wiki/01-User-documentation for example is always accessible as: https://raw.github.com/wiki/ThomasKaiser/lib/01-User-documentation.md

 

The whole wiki is just a git repo in itself so cloning it locally is also possible: https://github.com/ThomasKaiser/lib.wiki.git

 

 

Okay, cool!  I did some tinkering.  It looks like using the GitHub wiki for the Single Point of Truth for the docs would work really well.

 

here's my findings:

 

• you can SSH clone with your keys by inserting wiki in the main repo clone url (wiki gui only gives you https clone option)
• The raw wiki markdown files are named the same as the title, with no extra prefixes or suffixes
• The default wiki sidebar displays pages in a sorted fashion.  This allows us to rely on a naming convention to keep things grouped and allow for inserts
• direct access to the repo lets you add non-wiki files... ex: mkdocs.yml can reside within the wiki repo, along with style sheets etc

[Igor]

OK, let's use Github wiki as a base. I already done some rework. First part is more or less done, now going to script part and fine tuning on the top of it.

 

https://github.com/igorpecovnik/lib/wiki

[tkaiser]

Related note: Documentation might be written and structured nicely but still 'misleading' since it does not point out the severity of steps to take.

 

See this thread for example. Post #9: the usual 'SD card is crappy' issue. Why do people think about different partitions and waste their own and other's time testing irrelevant stuff out and asking in the forum?

 

Since we fail to say: "You run in boot problems? Check your PSU whether it's stable 5V @ 2A and check your SD card. NOW! Do not even think about asking in the forums before you tested your card. First requirement if you run in boot troubles is to show us f3 or H2testw logs so test now!"

[Tido]

Awesome Igor - I like it. But I guess it is not linked yet to: http://www.armbian.com/documentation/ ?

 

By the way, in the manual should be a small section "how to commit suggestion" or "help to improve this manual" and a couple words and links.

 

 

 

"You run in boot problems?

 

Check your PSU whether it's stable 5V @ 2A and check your SD card. NOW! Do not even think about asking in the forums before you tested your card. First requirement if you run in boot troubles is to show us f3 or H2testw logs so test now!"

This sounds to me like a standard FAQ section ?

 -> that could link to sections in the manual or just have some answers