Have docs point to gh pages

jayrbolton commented 6 years ago

This adds a link pointing to the new docs site (http://kbase.github.io/kb_sdk_docs) and replaces the README content with some initial documentation about this codebase. I also removed all the old documentation files (tutorial, howtos), that are now located in the kb_sdk_docs repo.

This is a PR into master, because master is ahead of develop with a lot of docs updates. Maybe we can merge master into develop so that they don't diverge further.

For the section on describing the codebase anatomy, I had a few questions for @MrCreosote to help fill it out:

what is /reports? I see it getting referenced build.xml as something related to Jenkins
what is /submodules_hacks? Also, doesn't this repo load jars from a sibling repo in build.xml? Do we still need /submodules?
what's up with all the templated test files in src/java/us/kbase/scripts? I wasn't able to grok how these get used or why these are templated.

MrCreosote commented 6 years ago

This is a PR into master, because master is ahead of develop with a lot of docs updates. Maybe we can merge master into develop so that they don't diverge further.

Yeah, we need to stop that practice. For this PR, merge develop into master and retarget it to develop.

MrCreosote commented 6 years ago

what is /reports? I see it getting referenced build.xml as something related to Jenkins

Looks like a JaCoCo coverage report. I'm guessing the tests generate it.

what is /submodules_hacks? Also, doesn't this repo load jars from a sibling repo in build.xml? Do we still need /submodules?

This is one of the few modules that doesn't need a jars sibling repo due to the /submodules jars repo (note there's also an auth repo in there). This was done to make it easy for users to use kb_sdk. With the dockerized version that's now available I'm not sure if we still need to make it a submodule - we could consider going the sibling repo route.

submodules_hacks contains (currently only one) hacks to make submodules work properly with sdk. You can see what happens in the Makefile submodule-init target. The perl auth client was revamped a while ago and I'm not actually sure if this is still necessary - @kkellerlbl handled the update so maybe confer with him - we might be able to delete it.

what's up with all the templated test files in src/java/us/kbase/scripts? I wasn't able to grok how these get used or why these are templated.

I don't see any in there - I see some Test* files in src/java/us/kbase/scripts/test, but they don't look like templates. If that's what you're talking about, they're used in TypeGeneratorTest.

MrCreosote commented 6 years ago

So we're only going to maintain the RST docs from now on right? the markdown docs are dead?

jayrbolton commented 6 years ago

@MrCreosote We can centralize SDK user docs at this repo. All the content of the markdown docs here for SDK users has been copied over to kb_sdk_docs and edited, so we don't want to have duplicate, diverging docs in both places. Also, we can put more documentation in this repo about the actual code here

jayrbolton commented 6 years ago

I merged this branch with both master and develop and am now targeting develop. Also I moved the "codebase anatomy" content into its own separate doc.

I think this one could be merged unless someone has feedback (cc @MrCreosote @sychan). You can see quickly see the newer readme here: https://github.com/jayrbolton/kb_sdk/tree/docs-point-to-gh-pages. Definitely not perfect but maybe good enough for now

MrCreosote commented 6 years ago

Who reviewed the new docs? Are there any old docs that are missing from the new docs?

MrCreosote commented 6 years ago

It looks like there's still some docs living here - why not just move them all to the other repo?

jayrbolton commented 6 years ago

Who reviewed the new docs?

Nobody has reviewed the new docs except for some JGI users. I'm happy to have any reviewers.. repo here: https://github.com/kbase/kb_sdk_docs

Are there any old docs that are missing from the new docs?

There aren't any except the couple I mention below (the pdfs in /doc)

It looks like there's still some docs living here - why not just move them all to the other repo?

The couple PDFs in /doc could definitely be moved over. I kept them in because those files are linked from some random places and I didn't want to break the links / hunt them down for now.

Come to think of it, I also think we should remove the /img directory, probably put it into kb_sdk_docs as well

MrCreosote commented 6 years ago

Ok, I think before merging this we should get @JamesJeffryes (and maybe others) to review the new docs and move any remaining documentation that only lives here to the new repo, and the README here should mostly just point to the new docs.

JamesJeffryes commented 6 years ago

@jayrbolton The new docs are a HUGE improvement! I looked them over and have a PR on that repo with updates. I approve this PR

jayrbolton commented 6 years ago

Added some more details to doc/codebase_anatomy.md, including a brief description of javacc
Removed the /img folder and put it in the kb_sdk_docs repo under sourc/images/app-icons

jayrbolton commented 6 years ago

Mergeable? Re-review?

jayrbolton commented 6 years ago

Updated lines in doc/codebase_anatomy.md from above review Re-reviewable / mergable

kbase / kb_sdk

Have docs point to gh pages #318