How to handle cross-repo documentation? about housekeeping HOT 26 CLOSED

are these what you think about for point "2"?

• https://github.com/raspberrypi/documentation
• https://github.com/locomotivecms/documentation

from housekeeping.

yes, something like that

from housekeeping.

Basically we can start from https://pages.github.com in a "Documentation" repo, and after that add styles/theme and use Jekyll (or plain MD files) to update.
The only side effect is that we need to maintain a TOC by ourselves.

from housekeeping.

we can have something like this really easily: http://radical.topics.it/documentation/

from housekeeping.

but would be able to simply use .md files?

from housekeeping.

yes, pure gh-pages, parsed by jekyll, supports both md and html

from housekeeping.

great, give it a try, porting some stuff, and see if we all like it

from housekeeping.

very basic, but it works pretty smooth: http://radical.topics.it/documentation/

from housekeeping.

👍 amazing, I love it 😄

from housekeeping.

I'd say that this can be a good solution, I'll close this and move to the repo issues to handle what needs to be done in migrate current doco. We'll re-open if needed.

from housekeeping.

no way :-|, after playing with Jekyll and GitHub pages for some times my conclusion is that it is a no-go.

• Front Matter headers must be there to accomplish our needs;
• Front Matter custom headers are required to make the ToC works;
• Front Matter permalinks are highly suggested but the layout of the static site is very different from the original md files layout on disk;
• automatic linking across internal pages is not supported;
• deploying to a virtual directory will complicate internal linking much more;

A working sample thought is here: http://radical.topics.it/documentation/desktop/quick-start/

It is really sad that the internal implementation of WiKi works differently from gh-pages, I'd say that we should stay with the WiKi, and:

• migrate the relevant portion of the doco to the "Universal" repo;
• live with the fact that we will have duplicate docu that must be kept in sync;

from housekeeping.

or use the documentation repo to have all the wiki down there and crosslinking from other repo wiki to there, but yes, I don't like it so much... leave this issue open to think a little bit more

from housekeeping.

I've spoken too early :-) it works as expected, with really minor issues (in my opinion): http://radical.topics.it/documentation/

Facts:

• do not uses static pages, use _posts instead;
• name posts according to the Jekyll convention year-month-day-slug
• place posts in subfolder if desired;
• to make links work internally use the Jekyll liquid syntax:  {% post_url post-name %} where post_name is the name of the markdown file with the subdirectory if used:
  • a post saved in _posts/sample/2010-01-01-my-article-title.md;
  • will be linked as {% post_url sample/2010-01-01-my-article-title %}, without the extension;
  • Jekyll will take care of generating the correct URL;
  • since we live in vdir post urls must be prefixed with the baseurl: {{site.baseurl}}, so the full syntax for internal links is: [link text]({{site.baseurl}}{% post_url sample/2010-01-01-my-article-title %})
  • use Jekyll categories to create paths, a post categorized as [desktop, presentation] will be available as /desktop/presentation/slug-post-file-name (without the date, Jekyll will remove it);

Sample Front Matter header

---
layout: article
title: "Quick Start"
categories: [desktop, presentation]
---

a permalink property can be added to customize the route generation overriding the default behavior based on categories.

The ToC will be auto-generated.

from housekeeping.

thank god, this is a good news, I was sad in the idea to abandon that, because it is nice 😄

just a question, is it normal to see stuff like [desktop] in the TOC:

from housekeeping.

actually yes, I'm playing with ruby and liquid to automatically build that ToC, trying to find the correct balance between a well-looking UI and the behavior I'd like to achieve. It's a beta in the end :-)

from housekeeping.

Take a look at this: https://github.com/RadicalFx/documentation/blob/gh-pages/_includes/toc.html

from housekeeping.

ok understood, so actually we can customize it in the way we like it :)

from housekeeping.

yes, we can basically do all what we want, we cannot use all the Jekyll plugins, only a subset is supported on GitHub, but that subset is enough.

from housekeeping.

we could add the link on [desktop] and write down simply as Desktop linked to http://radical.topics.it/documentation/desktop/intro/

from housekeeping.

my intention in that case was/is different:

• the ToC is generate for all the pages;
• items are sorted by "categories";
• indentation is based on the number of categories (since they can be seen as path segments);
• while iterating over the items generating the li elements, each time the category changes I print the category name, the intention is to have a "group header" as first item;
• the group header should be clickable and at click, via JavaScript should collpase/expande the clicked header and all the sub-items;

The issue is that categories are thought for "slugs" not as something to display, I'd like to find a way to have pretty categories "universal-apps" -> "Universal Apps"

from housekeeping.

take a look now :-)

from housekeeping.

great, I really like it 👍

from housekeeping.

A new hope :-)
http://docs.radicalframework.com/

from housekeeping.

it's like topshelf doc 😄

from housekeeping.

Yes, both powered by
https://readthedocs.org/

from housekeeping.

Migration started: http://radical.readthedocs.org/en/import-from-wiki
I imported the WiKi as is, lots of broken links and missing images. The nice thing of Read the Docs is that they support branches, as in the above link.

I'll close this one as I think Read the Docs is our best choice, moving the discussion in the docu repo

from housekeeping.