doc/ivanx is confusing

[knghtbrd]

The original (and current as of December 2015) website for A2SERVER contains content that is desirable to maintain from a historical perspective, but pretty much everyone agrees that the HTML is, um, limited. :)

The HTML was converted into Markdown format for easier reading outside a web browser and stuffed into doc/ivanx. The problem is that when you're searching through the code, you keep getting false hits from this stuff that shouldn't be modified.

Proposal for a rapid-development roadmap that preserves the historical stuff as historical:

1. Create a website repository in RasppleII.
2. Take all the Markdown for A2SERVER and A2CLOUD and the not-yet-converted Markdown for Raspple II and stick it in there. Complete with code from circa October.
3. Add a Kramdown template and whatnot to make it render as-is so that it more or less resembles the original HTML. This has already been done as an example, but do it for real this time.
4. Deploy the Markdown and generated HTML somewhere we can see it and test all the links and whatnot, complete with old (circa October 2015) code. Because it uses an old version of the code
5. Generate a GitHub release with a tag for the historical stuff as-is, old code and all.
6. Modify the website to refer to GitHub source instead of mixed-in source and delete the source.
7. Deploy that tree to wherever testing stuff ended up and again test all the links.
8. Deploy it live once we know it works.

@IvanExpert, how does that sound to you?

[knghtbrd]

I've started doing the early stages of this, mostly because they represent changes to doc/ivanx/* that I intended to make anyway (modifying those Markdown files so that they can render to something that matches the content as of October). I'll probably finish that in the next day or two leading up to Christmas.

Beyond that, if we decide to push ahead with it, I think I can have it ready by the time 1.3.0 is done so that we can deploy them together. If not, very shortly after. The layers of actually accomplishing it are described in RasppleII/website@e225fcd which is kind of a long commit log for what it is, but explains what I'm doing and how far I can get before we need to make some decisions.

[knghtbrd]

Aside from the nasty-looking a2server_lan.md, the webification of the doc/ivanx tree in RasppleII/website is looking pretty good so far.

The A2SERVER pages and the Raspple II page are done, and the Markdown is clean enough other than _lan which needed that <span> crud to do the spacing. I need to have a look at the CSS still to remove a few things we don't use anymore, and I need to actually stick the templates somewhere useful.

The other thing that's not done for these is that the templates I'm using lack the JS analytics functions found on the ivanx.com pages. But this so far represents a mostly-complete pass 1 through the stuff for archival purposes and I figure that's not so interesting for analytics.

[knghtbrd]

RasppleII/website@6dec311 has added a script to build the web pages from markdown in a subdirectory named _site. This is all still somewhat preliminary since I'm still working on the pages—particularly a2cloud/index.mdwhich is the most complex of all the Raspple II pages, but even that (as rendered to HTML) is pretty much what I intend to use. It's just the Markdown source code I'm cleaning up a bit.

@IvanExpert, if you want to have a look at it now, you need kramdown (gem install kramdown requires sudo on a Mac) so something like this will do:

sudo gem install kramdown
git clone https://github.com/RasppleII/website.git
cd website
./build_site.sh

This will generate a directory named _site. Like Jekyll and its derivatives, the script just blows that directory away when it runs, so don't serve out of it! :D But doing so will let you see the web pages more or less in their final form. I say more or less because I still need to go through all of the links, fix the dead ones, and clean up the context in places. But none of that will affect the generated HTML.

At this point the generated HTML will only change if I see something broken.

The content doesn't reflect changes to the website since October 2015 intentionally. My first goal was to remove the archival stuff in doc/ivanx in A2SERVER and A2CLOUD. If you like how this has come out, I'll remove those directories from our source code trees which will close this issue.

From there I will:

1. Fix up and test the links
2. Generate a release for the archive website (probably 2015.10.14a)
3. Branch that release off as a2_history in case there needs to be a 2015.10.14b or something
4. Proceed with bringing website content up to current standards. I've already got one A2CLOUD edit you've made since since I pulled the A2CLOUD page: RasppleII/website@b353230 but there are a couple of others for A2SERVER as well.
5. Begin getting this ready for deployment.

Really we ought to have a proper generator at some point so we can take advantage of all the toys the cool kids use to make websites easily these days, but this will do until I figure out enough of how those things interact to start using them. :)

Feedback welcome.

[knghtbrd]

As far as A2SERVER is concerned, this issue is now closed. We still need a solution for files/ in that we can't just stuff a 4GB OS image on github.io, but perhaps that too has a solution since our Raspple II OS image isn't exactly a minimal Raspbian installation.

Anyway, the historical content is now located in RasppleII/orig-archive, which resolves this issue.