Update Documentation for the v3.0 Milestone

[ilexp]

Summary

With the overall cleanup and API changes that are scheduled for milestone v3.0, it will be crucial to keep the documentation updated, while at the same time providing the old v2.x docs for anyone who hasn't updated yet or will stick to v2.x for an extended period of time.

Analysis

• Basically just go over all Wiki articles and make sure all the code runs and all the code snippets are still correct.
• Double-check the Getting Started guide. For most users, it's the first thing they'll see and try.
• Similar to the main repository, the Wiki will need some kind of a release-cycle based versioning.
  • Clone all the docs into a v3.0 folder and edit articles in there.
  • Edit the Wiki main page to include a link to the v3.0 main page and a notice about the version state.
  • When releasing v3.0, move the old docs into a v2.x subfolder and the new v3.0 docs into the main folder.

[ilexp]

Issue:

• In GitHub Wikis, all pages are identified by their name, without specifying a path.
• Having multiple versions of the same page available at the same time would potentially cause a lot of problems and complicate things.

Solution A:

• Instead of providing docs for both versions, actually branch the wiki repository and merge it back when v3.0 is released.

Solution B:

• Convert all wiki links to project-relative path links. See also: Gollum Wiki
• Double-check whether it is possible to have non-unique page names, consider adding a suffix otherwise.

[ilexp]

Response from the GitHub staff on that matter:

Hi Adam -

Thanks for getting in touch and asking us about GitHub Wikis. I'd like to address each part of your reasoning and offer some context.

In one scenario, there would be one folder per major version in the wiki repo, with the starting page and footers providing links to either one. However, as far as I've read the docs, every Wiki page needs to have a unique name while paths are ignored, so I'm unsure whether this would be considered a stable solution, or even a possible one. Alternatively, each major version could have its own Wiki branch, if these branches are somehow publicly accessible. Is there any way to browse the entire Wiki in a specific (non-master) branch?

Although wikis are Git repositories and every change you make is a commit that you can view, we don't currently have any facilities for dealing with different public Wiki versions in the same way you would a repository and the related releases and branches.

Also, there isn't a way to browse the entire Wiki in a specific branch, but you can look at the specific commits. I recommend checking out this article our team wrote about that:

https://help.github.com/articles/viewing-a-wiki-s-history-of-changes/

You also mentioned this option:

Moving the entire documentation into a distinct repository and utilizing branches to maintain different versions simultaneously would be a good solution workflow-wise, but not very elegant, since I would need to redirect users out of the Wiki and, in the process, also leave behind Wiki layout and features like sidebar or footer.

I think this is the best way to go because it would give you the different Wiki versions at a more granular level than the GitHub Wiki provides.

I hope that helps, but let me know if you have any other questions!

All the best, Francis

[ilexp]

Prerequisite: Issue #455

[ilexp]

Another possibility would be to create a new AdamsLair/duality-docs repository where all documentation is hosted in markdown form. There could be a dualitydocs.adamslair.net redirect or mirror URL that would be linked instead of the Wiki, and the Wiki itself could be reduced to a single page linking there.

This new repository could then be transformed unto a github pages repo with a documentation friendly Jekyll theme, like one of the following:

• MkDocs
• IOOS
• Minimal Mistakes
• Jekyll-doc
• Docster

MkDocs actually looks pretty good, because it's so fast / responsive and favors swift display over animation - textures and style can still be changed. Edit: Actually, MkDocs doesn't seem to be a Jekyll theme at all. Removing it from the list.

One difficulty will be to find a documentation theme or figure out how to write a custom Jekyll theme that is compatible with GitHub. The officially supported themes are here.

[ilexp]

Progress

• Documentation has been moved to the new docs repo as linked above, the previously mentioned issues have been solved accordingly.

ToDo

• Go over all wiki pages and make sure they still apply to v3. Make changes where necessary. Copy updated pages to the v3 folder structure.

[ilexp]

Progress

• Fixed undefined sorting in sidebar version labels.
• Ported the following pages to v3:
  • Branch Descriptions
  • Choosing Duality
  • Components
  • Creating Bullet-Like Objects
  • Guidelines / Best Practices
  • Guidelines / Common Pitfalls
  • Custom Renderers

ToDo

• Go over all remaining wiki pages and make sure they still apply to v3. Make changes where necessary. Copy updated pages to the v3 folder structure.

[ilexp]

Progress

• Ported the remaining pages to v3.

Done. Closing this.