[400] - Implement Documentation Software Solution

[lanefu]

Task derived from Inquiry / Discussion thread http://forum.armbian.com/index.php/topic/1337-documentation-software-proposal-for-armbian-wiki/

 

Commit against github issue

[lanefu]

* wiki updated to new naming convention

* still working on mkdocs.yml generation script. filename parsing done. working on jinja iteration

* todo: document the documentation process

 

Tapatalk thinks its important to tell you im using tapatalk from a phone.

[Igor]

One more thing, shall we rather move docs out of wiki to normal repository? We can have separate, less strict list of collaborators and no need to have an open edit mode?

[lanefu]

One more thing, shall we rather move docs out of wiki to normal repository? We can have separate, less strict list of collaborators and no need to have an open edit mode?

i think its a good idea to move to a separate repo.

 

are you suggesting markdown files in a repo w/o wiki or moving to a new repo and using new repo's wiki?

 

Tapatalk thinks its important to tell you im using tapatalk from a phone.

[Igor]

No wiki, just repository.

 

Wrote on mobile phone

[lanefu]

No wiki, just repository.

 

Wrote on mobile phone

okay cool.

 

 

Edited July 2, 2016 by lanefu

[lanefu]

@Igor

 

Okay the new docs repo has been updated.

 

I ported the docs to the new repo, added a working mkdocs.yml generator in the the tools folder, and provided some brief docs on how to use it / generate mkdocs.

 

It's not quite sorting the way I want, but the Parent Categories are grouping correctly.   This should be sufficient to let others contribute, polish etc.

[Igor]

Cool, I also did few things on the way:
 

- docs.armbian.com is updated auto when new commit is done to lib.docs, checking via cron at the moment

- wiki @lib is closed

- I moved main documentation link to docs.armbian.com since it's better than what we have right now in any case.

BTW: Do we really need brackets [ ] in URL? They are URL unfriendly ... any other option?

[lanefu]

Cool, I also did few things on the way:

 

- docs.armbian.com is updated auto when new commit is done to lib.docs, checking via cron at the moment

- wiki @lib is closed

- I moved main documentation link to docs.armbian.com since it's better than what we have right now in any case.

BTW: Do we really need brackets [ ] in URL? They are URL unfriendly ... any other option?

the filenames with brackets are causing problems? any example on when its problematic / annoying?

 

maybe just a single underscore _ between parent and child?

 

Parent-topic_child-topic.md

 

Good point.  Brackets are considered unsafe.   I'll switch to surrounding with underscores.

 

_Parent-topic_child-topic.md

 

Tapatalk thinks its important to tell you im using tapatalk from a phone.

[lanefu]

I've updated the repo, code, and readme to use _underscores_ instead of brackets.  

 

 Haven't seen your cron update docs.armbian.com yet.   perhaps i'm being impatient.

[Igor]

I've updated the repo, code, and readme to use _underscores_ instead of brackets.  

 

 Haven't seen your cron update docs.armbian.com yet.   perhaps i'm being impatient.

Even small scripts can be little wrong Fixed. Before we fixed the naming, PDF creation must be double checked. Leading _ looks a bit odd - can we be without it?

[lanefu]

Even small scripts can be little wrong Fixed. Before we fixed the naming, PDF creation must be double checked. Leading _ looks a bit odd - can we be without it?

ya i guess that's all that's really needed. i was being lazy about retooling my regex. this will be simpler at least. ill get it updated

 

Tapatalk thinks its important to tell you im using tapatalk from a phone.

[lanefu]

Okay I've updated site, tool readme to use the Parent-Topic_Child-topic.md naming convention.

[Igor]

Extra security  ... fixed. One minute cron, so you don't need to wait long.

 

It looks better now. PDF check, some Youtube solution ... working on content. 

[lanefu]

Extra security  ... fixed. One minute cron, so you don't need to wait long.

 

It looks better now. PDF check, some Youtube solution ... working on content. 

 

@Igor is your cron running mkdocs against the mkdocs.yml that is checked into the repo, or are you running the python script in tools to generate?

[Igor]

Python script.

 

Wrote on mobile phone

[lanefu]

mkArmbianDocs.py tentative enhancements:

 

• add sorting functionality
• add preset to sort prefered parent categories in a specified order
• sort unspecified parent categories at end, in alphabetical order
• sort sub-topics in alphabetical order

[miked]

 

mkArmbianDocs.py tentative enhancements:

 

• add sorting functionality
• add preset to sort prefered parent categories in a specified order
• sort unspecified parent categories at end, in alphabetical order
• sort sub-topics in alphabetical order

 

 

Do you have a plan for how to do this?

I think the order of subtopics will need to be controlled by doc writers, too. For example, "Build Options" (is this a subtopic?) shouldn't come before "Build Process" Edit: Bad example "Build Preparation".

 

Is mkdocs.yml auto-generated so that people can add new files without having to edit anything?

Is it feasible to have a human-edited mkdocs.yml (maybe a template), which controls the order of categories and topics, but have the build script add any remaining files?

 

 

 

 

My goal for sort order is to have the docs read like a tutorial+reference book. It would be something like "Intro/where to find what you're looking for, getting started, advanced, developer guide, reference". If you read the web pages or pdf from start to finish, nothing should feel like it's out of place.

[lanefu]

Do you have a plan for how to do this?

I think the order of subtopics will need to be controlled by doc writers, too. For example, "Build Options" (is this a subtopic?) shouldn't come before "Build Process".

 

Is mkdocs.yml auto-generated so that people can add new files without having to edit anything?

Is it feasible to have a human-edited mkdocs.yml (maybe a template), which controls the order of categories and topics, but have the build script add any remaining files?

 

Mkdocs is currently generated by this script after commit.     I have a vague plan on how to add the sorting functionality.   I'm in dangerous waters now where my intended simple solution is at risk of creating complexity and pissing everyone one off.    

 

Let me think through this.  For subtopic would a 2-digit prefix be sufficient for sorting? 00-99? 

 

 

My goal for sort order is to have the docs read like a tutorial+reference book. It would be something like "Intro/where to find what you're looking for, getting started, advanced, developer guide, reference". If you read the web pages or pdf from start to finish, nothing should feel like it's out of place.

 

Great goal--totally makes sense.   I'll do my best not to hinder that.

[Igor]

I'm in dangerous waters now where my intended simple solution is at risk of creating complexity and pissing everyone one off.    Let me think through this.  For subtopic would a 2-digit prefix be sufficient for sorting? 00-99? 

 

What if we use a fixed mkdocs configuration? We need to sacrifice something.

[miked]

Mkdocs is currently generated by this script after commit.     I have a vague plan on how to add the sorting functionality.   I'm in dangerous waters now where my intended simple solution is at risk of creating complexity and pissing everyone one off.    

 

Let me think through this.  For subtopic would a 2-digit prefix be sufficient for sorting? 00-99? 

 

 

 

Great goal--totally makes sense.   I'll do my best not to hinder that.

 

Oops Igor beat me to it...

Why not just let a mkdocs.yml file specify the order? This way the organization is part of the content, rather than controlled by the file naming.

I guess with numbers you could strip out the prefix when building the docs, otherwise urls would change if their order changed.

 

 

I experimented with an idea that has a mkdocs.yml template with sections that look like this:

  - 'Developer Guide' :
        - 'FEL boot' : 'Developer-Guide_FEL-boot.md'
        - 'User Configurations' : 'Developer-Guide_User-Configurations.md'
        ##INCLUDE Developer-Guide_
  - 'User Guide' :
        - 'Getting Started' : 'User-Guide_Getting-Started.md'
        - 'Advanced Features' : 'User-Guide_Advanced-Features.md'
        ##INCLUDE User-Guide_

It seems mkdocs treats # as a comment, so this file doesn't break mkdocs if our processing gets broken.

I have a bash script replace "##INCLUDE xxx" with all the files in docs/*xxx*.md that are not already included in the template.

 

This way, a doc writer can specify the order of everything as much as they want, and also leave a place for any new files. It also has the advantage that the displayed titles can be changed without needing to change the filenames (and subsequent URLs).

[lanefu]

yeah lets go static. was a fun attempt at least

 

Tapatalk thinks its important to tell you im using tapatalk from a phone.

[miked]

I've added a navbar to the top of docs, taken from www.armbian.com and modified slightly.

I did this to make the docs feel like part of the main armbian site, and to provide an always-visible link back.

However now I wonder if this is unnecessary, as Sources and Forum are not set up that way.

 

Problems:

- This is stored in the documentation repo, and the navbar html would need to be separately maintained from www.armbian.com's navbar.

- I had to duplicate and edit the readthedocs theme "base.html", adding only one line. If updated theme source is obtained, this would have to be updated too.

- The minimum relevant css was also copied, and I might have missed some. For example the font looks different.

 

 

 

I also changed the docs order.

I can't build the docs on the server... who can do this?

Hopefully I haven't screwed anything up! I should be on hand in case these changes break anything...

 

 

 

Also might want to verify that the readthedocs source I have is the same as on the server. The following should show only one line added:

diff `locate readthedocs/base.html` readthedocs_custom/base.html

[Tido]

 

I've added a navbar to the top of docs,

It works on my mobile phone with this navbar, but it does hover with a distance from the top (Firefox mobile).

[miked]

It works on my mobile phone with this navbar, but it does hover with a distance from the top (Firefox mobile).

Oh no. Thanks. This happens with small browser windows too. The easy fix blocks content underneath, so I'll have to figure out how to do this right.

 

Edit: Removed position:fixed until a proper fix can be found. Maybe keeping it onscreen all the time is not worth doing?

[svkatielee]

Nice job on the Documentation.

Is this where I could give feedback?

 

 1. It would be really helpful if you included a mechanism to provide "info valid as of date" along with each subtitle or at least each page.

    The entire internet has forgotten the importance of dating information.

    For instance: Build Process -> Desktop installation : hardware acceleration only...

       If it is still true, will someone remember to update this when it changes?

 

 2. It feels like the title is missing for some pages.

        Build Preparation , Build Options, User configurations

 

 3. Apparent formatting mistake in table at: Hidden options for advanced users (default values are marked bold)

        USE_CCACHE - entire line is bold

        FIXED_IMAGE_SIZE - all in left cell

[lanefu]

@svkatielee

 

see this thread for formatting content...

 

https://r.tapatalk.com/shareLink?url=http%3A%2F%2Fforum%2Earmbian%2Ecom%2Findex%2Ephp%3F%2Ftopic%2F1532-%5B392%5D---documentation-rework&share_tid=1532&share_fid=1017055&share_type=t

[392] - documentation rework

 

the documentation repo is meant to have more generous access. If you'd like access please ask igor and provide your github userid

 

Tapatalk thinks its important to tell you im using tapatalk from a phone.

[miked]

 3. Apparent formatting mistake in table at: Hidden options for advanced users (default values are marked bold)

Thanks, I've just fixed this. I don't know the answer to the first 2 issues.

 

mkdocs was treating the list as a table. I replaced the first "|" with "|" to stop it. Adding blank lines between the items also works but makes the list look different from the others on the page.

[Igor]

YouTube implementation - perhaps like this?

 

https://github.com/mkdocs/mkdocs/issues/243

[Igor]

YouTube implementation - perhaps like this?

 

https://github.com/mkdocs/mkdocs/issues/243

 

@lanefu

I am a bit lost  Where to put this snippet to get YT working?