Update repo docs to v2 of ClassDB

[afig]

This commit updates the documentation that will be converted to the ClassDB website. The docs are sourced from the latest version from the development of ClassDB M2.

The index.md and home.md pages were merged so that their file contents are the same.

A version that was converted to GitHub Pages is available for review here: https://afig.github.io/classdbDocsTest/Home

Note that any future changes to a wiki page that should be in M2 will need to be manually added to this PR, or in a separate PR into the dev/master branch if they are performed after this PR has been merged.

Also, this is being merged into dev now, but the changes will not show on the ClassDB webpage until dev is merged into master.

Just as a reminder, Issue #141, which is related to this PR, should be closed once M2 is released.

Fixes #186

[wildtayne]

Overall, the docs work well on the demo. I noticed a couple issues:

• It looks like Home.md still mentions 'this wiki', it should probably be 'this site' (index.md looks right though).
• The frequent views page links to Schema-Placement-Criteria.md and Object-Type-Criteria.md, however they are not added to the PR. I can remove the reference to them, or we can add the to the PR.

[afig]

Thanks for pointing out these issues @srrollo.

The first was that I had forgotten to update the test website with the latest version of index.md and home.md. The versions in this PR are up to date and say "this site".

As far as Schema-Placement-Criteria.md and Object-Type-Criteria.md go, I suppose the solution depends on whether we consider then design pages or not. They're somewhat in the middle.

If we keep them then it might be a good idea to add links to them in the table of contents. If we don't keep them, then we could still have links to their wiki pages, with some sort of note that they are not regular documentation pages.

[smurthys]

I think we should keep the design pages because they add value. Here is what I did in the Wiki for trial:

• Added a Design Choices node to TOC
• Added a Design Choices page
• Under the Design Choices node and in the Design Choices page, added items Database Design, Views and Functions, and Object Placement

I propose renaming the existing criteria pages to match the new sub-nodes and update links elsewhere. Also, I don't recall having a page about the conceptual and physical design. I propose a simple Database Design page with that information.

[wildtayne]

I think the new design docs node is a good idea. I've updated the Views and Functions and Object Placement to reflect their new names.

[smurthys]

FYI, I renamed Database Design to Data Design and adjusted links.

I am presently drafting the Data Design page. Will comment again when I have something for review.

[smurthys]

A draft of Data Design is ready. Please review/edit.

Ideally, it will be nice if clicking the embedded image opens the full-size image instead of having to show the anchored text "see full-size...". Unfortunately, I can't afford the time to figure out if/how that is possible.

The issue of HTML docs showing as raw text in the Wiki version is documented. This is acceptable behavior because it should open correctly on the docs site.

BTW, I feel the page User Logging should be titled Activity Logging. FYI, I edited the opening paragraph on that page to say "activity log" instead of "user log".

[afig]

The Data Design page looks good. I was able to make it so the embedded image links to the full size counterpart. The image syntax can be nested in a link, like so:

[![ER-Schema-small.png](ER-Schema-small.png)](ER-Schema.png)

I have confirmed that this works even when the page is converted to HTML via GitHub Pages. I also added a hint above the image that says "Click on figure to view in full size". Not sure how others feel about the necessity of this hint.

I agree that User Logging would be better named Activity Logging.

[wildtayne]

I also like the new Data Design page. I've renamed User Logging to Activity Logging, and updated all links to it.

[smurthys]

I revised the TOC and the Design Choices page to fix the inconsistency in the character case of the entries I had added.

The solution to open the full-size image is good. I edited the preamble text to what I think flows better.

@afig Would you be able to publish the revisions to GitHub Pages for preview?

[smurthys]

I just updated the text in Adding Users page related to the flow chart.

[afig]

I agree that having the text in that location flows better.

The latest version, including this last change made to Adding Users is ready for preview.

[afig]

Thanks for the confirmation that everything checks out, @srrollo. I've pushed the recent changes made to the docs into this PR. I think we're about ready for this to be merged in, pending at least one more review.

[smurthys]

The preview looks good. On TOC, I see blank lines around before/after some entries.

[afig]

Unfortunately, I do not think we can easily remove that extra space. The theme seems to add that extra vertical space when moving back from a list indent.

The same spacing exists on the current ClassDB website: https://dassl.github.io/ClassDB/Table-of-Contents

[KevinKelly25]

Still looking through the preview @afig . It looks good, so far the only very tiny issue I have noticed is a tiny misspelling of postgres at the end of the first paragraph in Setup-> prerequisites.

All links are working for me.

[smurthys]

Ah yes, I'd forgotten about the issue with vertical space.

I'm ok with this version provided we correct the issues @KevinKelly25 finds.

[wildtayne]

I've fixed the misspelling @KevinKelly25 pointed on on the wiki.

[afig]

Thanks everyone for the thorough reviews. The last commit adds the fix to the typo @KevinKelly25 found.