Doc system - Githubissues

Hi,

Sorry for this taking so long. As I got more familiar with Sphinx, especially where making helpers were concerned, I went through more than a few rewrites of key aspects that would've caused a lot of churn as everyone started putting docs together.

Since the frontend uses Python, and since the docs are going to be referencing Python content frequently (or at least, I assume it will), I went with a Python-based library for static webpage generation. I did some research and most things I was finding were pointing to Sphinx as the de-facto Python documentation tool - which actually includes the Python docs themselves (post 3.3, I think, but look at the footer at the bottom of the page).

There's a good chance that experienced Python uses would've encountered Sphinx before, so I think the barrier to entry should be the smallest going with Sphinx vs. other Python libraries, or vs. a Rust-based alternative (which I also looked in to).

I went a different route with PR-opening this time as well - I'm not going to cover user guides here, but instead refer you to the documenting section on the webpages. I actually have content and I think (hope) I have enough there to get everyone started and if the content there is either insufficient or confusing, then I can fix it there and it'll go live instead of being buried in a PR for others to stumble upon. To this day, we don't have anything in the O1 docs section so I wanted to try to nip that this time around too, as I think that's at least partially the reason that documenting with O1's web stuff never caught on internally (at my company at least) outside of the core team or power users.

I say that, but I also deferred a bunch of the actual "how do you do stuff" to the Sphinx guides, which luckily are quite complete when the app is already in place. Since Sphinx is a popular library as well, there's no shortage of stack-overflow questions and other bloggers putting up simple how-to guides. The premise of the docs I wrote kinda go "We use Sphinx - here's some links to go learn about that, then come back and I'll tell you about using Sphinx in Origen" which I think is the way to go as I don't think we want to (and I definitely don't!) want to signup for rewriting Sphinx's existing docs, just over here.

I think the biggest non-obvious change between O1 and O2 docs are that Sphinx uses RST as its markup language and lot of Sphinx stuff is dependent on that. RST isn't bad and definitely has the edge for scientific and mathematical writing (which I'm looking forward to trying out for RF-related stuff), but to be perfectly honest, I prefer markdown. For just general docs, markdown flows much more fluidly than RST does and is less verbose. I do, however, have markdown working in theory, but the developer installation guide is the only section its used on, so it hasn't really been put through the gauntlet yet. Also, long term, I think having a mix of RST and markdown in the core might get a bit confusing, so I'd recommend we stick to RST (again, at least in the core. In your apps, do whatever). Most of the "sphinx stuff" is tied to [rst roles](), and although I do have embedded rst in markdown, it's a bit clunky when you compare to using straight RST.

I think I've hit on most of key items from O1 - we have templating, a connection to the origen app, and a starting CLI for generating pages.

The big holdups I had on this was constantly rewriting how the user's should write docs. I'm more confident in having that interface locked down now via the origen_sphinx_extension, shorthand, and extlinks, so jumping into this and writing some docs shouldn't be a cause for churn for future PRs. That said, I'll open an issue to track several WIP items. These are things which should either increase robustness, be transparent to existing docs, or otherwise meld seamlessly into whatever's there currently. Two examples just to show what I mean for the latter are the stupid jittery sidebar in pre0, which happens when trying to scroll but the page's content isn't sufficient for the scrollbars (you may need to adjust your browser window size to replicate it, but trust me, its there) or the spacing in between <p> tags in nested lists. Both of these things I intend to fix, but I don't really feel those are must fix items to just get some usage out of what I currently have. I don't necessarily think any one thing on that issue is difficult to fix, but, depending on workloads, getting through all of them may take a bit of time. And, like I said, none of those should be critical or causes for churn down the road.

Also, some of the robustness things are going to take a while. I had to dig a through a ton of Sphinx source to get shorthand to work the way I wanted. Its maybe 90% of the way there, but I need to now get into the doc util source to really take it to the next steps.

A few things to note though:

To test out shifting in navbar items, I added the [community]() section to this. I added some content to it, but I'd appreciate it if @ginty would take a look.
One thing I really (I mean, really) wanted to do is make it easy to reuse commonly used internal and external references. I a big problem I have internally is finding dead or outdated links. I hope that by using shorthand and extlinks, we can reduce a lot of that. Shorthand combined with Sphinx's own consistency checks should validate most of the internal links (save for the python-domain, which I'm looking into it, but this seems to be a larger Sphinx problem, not solely an Origen one).
Because of this, I kinda worded the documenting the core section for developers maybe a bit too strongly? @ginty, could you take a look at that as well? I tried to word at as "docs should be written this way" without making it sound too much like a recommendation. :p
- Even though I've proofread the docs, and still am making some passes through it, please point out areas where I broke my own rules if you see them. I'm sure there's still hanging around and I'll get them fixed.
I have placeholders for a lot of other items but honestly most of it was just to test out referencing, linking, etc. We can move those pages around if it makes sense and any places where I reference those should get flagged during consistency checking where only the shorthand target needs to be updated.

@info-rchitect, I changed the compiler around a bit to tie into the web generation. I updated the specs and the interface you had before should is still be valid but you may want to take a look nonetheless.

I think that's about it. Again, I'll open an issue we can add non-critical fixes too. There's a ton of content here too so I'm assuming this'll stay open for a while.

Lastly, and kind of unrelated to this, but some of the crates won't build in Windows with the gnu compiler. I switched the Travis script back to using msvc, which is what Rust has as the ]official installation](https://www.rust-lang.org/tools/install), so I think this config is more valid than the gnu one.

TL;DR - I'm finally comfortable enough with the docs to start a PR. I've got the user guides in place for the more practical stuff as well as some notes on documenting the core itself.

Origen-SDK / o2

Doc system #114