Gitbook is not building this version of the documentation.

[gsrohde]

I assume we want to host this documentation at Gitbook.com, but if not, this is not a problem. But then we need to decide where we do want it hosted. (Also, it is important to know where the official documentation is to reside for the purposes of linking to it. For example, I'm assuming we will want to change the links for www.betydb.org's "Docs --> Data Entry" and "Docs --> Data Access" menu items from the Authorea documentation to the Gitbook documentation.

My work-around for now is to run gitbook server on my local machine so I can see what the build looks like.

As I mentioned in earlier e-mail, my guess is that the builds aren’t being triggered (see https://help.gitbook.com/build/index.html), possibly because you changed the book name or owner (?)—see the bottom of the page at https://help.gitbook.com/github/index.html. You might try deleting and re-adding the webhook.

[dlebauer]

Is it possible to pull --> compile --> add documentation to BETYdb when it is deployed? (not add it to the repository, but host it locally)

On Tue, Apr 5, 2016 at 4:34 PM Scott Rohde notifications@github.com wrote:

Assigned #2 https://github.com/PecanProject/betydb-documentation/issues/2 to @dlebauer https://github.com/dlebauer.

— You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub https://github.com/PecanProject/betydb-documentation/issues/2#event-615779013

[dlebauer]

regarding the broken builds on gitbook -- I just updated the webhooks to point to the correct repository. Can you check that they work now?

On Tue, Apr 5, 2016 at 4:50 PM David LeBauer dlebauer@gmail.com wrote:

Is it possible to pull --> compile --> add documentation to BETYdb when it is deployed? (not add it to the repository, but host it locally)

On Tue, Apr 5, 2016 at 4:34 PM Scott Rohde notifications@github.com wrote:

Assigned #2 https://github.com/PecanProject/betydb-documentation/issues/2 to @dlebauer https://github.com/dlebauer.

— You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub https://github.com/PecanProject/betydb-documentation/issues/2#event-615779013

[gsrohde]

If by your first comment you mean incorporating the various Gitbooks pertaining to BETYdb within BETYdb itself, this is certainly doable and perhaps even an excellent idea. By being part of the BETYdb deployment itself, it would be unmistakably clear that the version of the documentation bundled with BETYdb is the "official" version.

I'm still not seeing a correct build on Gitbook.com. Here's a screen shot:

Even if we don't plan to host the official versions of documentation at gitbook.com, it would still be nice to get this working. For example, gitbook.com provides an easy way to make line-by-line comments on content.

[dlebauer]

It is working now

[gsrohde]

@dlebauer The latest update from pull request #7 isn't showing up at https://pecan.gitbook.io/betydb-documentation. Could you check what the problem is?

[dlebauer]

@gsrohde I've re-enabled the hook (not sure what happened). However, gitbook wants to force its old copy onto the github master branch. I think https://github.com/PecanProject/betydb-documentation/commit/914a524e10caf4ed57cabad80a020337a42fa526 reverts all of the changes you made. I am not sure how to get out of this one - I've tried rebasing but the changes don't propagate to gitbook. Before I copy all of the files by hand and re-check them in, do you have any suggestions?

[gsrohde]

@dlebauer I'm not sure I understand what's happening here. Were there a bunch of changes on GitBook that never made their way into the GitHub repository, perhaps because the hook was broken? And did GitBook then automatically check all those changes into GitHub as soon as the hook was re-enabled? Does GitBook have its own record of the document history, or is that now lost? I assume that you somehow want to merge what was in GitBook before re-enabling the hook with what was in GitHub.

Also, does the gitbook branch have some special significance—is it something that GitBook creates? Or did you create it for some reason? Right now, there is very little difference between what is in the gitbook branch and what is in master, but where there are differences, it seems that what is in master is what is displayed by GitBook. [Update 9/4: I just noticed one may select which branch is displayed in GitBook. The master branch is referred to as "primary version". This is probably settable.]

Commit 914a524 seems to keep most of my changes but it does some baffling things. For example, a new directory installing_betydb is introduced, and several files are moved there. So comparing installing-betydb-web-application.md with the moved version using the command

git diff de92d9:./installing-betydb-web-application.md HEAD:./installing_betydb/installing-betydb-web-application.md

shows that they are for the most part the same except:

1. The page heading has been modified (from "Deploying a Production Copy of the BETYdb Web Application" to "Deploying BETYdb on CentOS").
2. Line wrapping changes.
3. Backslash quoting is sometimes introduced.
4. Almost all of my footnotes disappeared.
5. Blank lines are introduced.
6. Other special characters (e.g. ** for bold) are sometimes quoted and moved around.
7. Opening block quotes (triple backtics) without a language specified will be specified as "text".
8. The Apache server configuration blocks listed in step 20 disappeared.

I think, with the exception of disappearance of the footnotes and the rather disastrous removal of the Apache configuration code from step 20, most or all of the changes are transparent to the reader of the document, but I haven't really carefully read through what is displayed to check this.

installing-betydb-web-application.md is the file I revised most extensively. I haven't yet checked the other files I changed. It's possible most of these are essentially the same and possibly renamed into subdirectories.

I suggest that before you do anything drastic, that I go through and take a closer look at the other files as well.

[gsrohde]

@dlebauer Shall I go ahead and try to patch this up?

[betydb]

Yes please if you can! On Tue, Sep 4, 2018 at 9:34 AM Scott Rohde notifications@github.com wrote:

@dlebauer https://github.com/dlebauer Shall I go ahead and try to patch this up?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/PecanProject/betydb-documentation/issues/2#issuecomment-418434851, or mute the thread https://github.com/notifications/unsubscribe-auth/AErs3LP4qFuSxCQFZBRiYMg7zzfnaYOcks5uXquigaJpZM4IAdeF .

[gsrohde]

@dlebauer:

It seems that GitBook has done a major rewrite of their rendering engine since we first started using them to host our documentation. While the new "v2" version has several nice features, it drops support for a number of things, including PDF exports and most notably, plugins, though the functionality of certain plugins, including "atoc", "github", and "image-captions", have become first-class features of the new GitBook version, and it seems that there are plans to eventually incorporate the features of the mathjax plugin as well. Read more about the differences between v2 and the "legacy" version here: https://docs.gitbook.com/v2-changes/important-differences. One important feature which I have used extensively and is not supported in the new version is footnotes. Also, the flavor of MarkDown used in v2 seems different from that used before and from that used on GitHub.

Note that the legacy version is still supported. David, do you recall explicitly doing an upgrade at some point? To get a sense of the different look of the two versions, you can compare https://pecan.gitbook.io/betydb-documentation with https://gsrohde.gitbooks.io/betydb-technical-documentation/content/. To produce the latter, I forked the PecanProject/betydb-documentation GitHub repository, backed it up to just before the last commit (the one that stripped out a bunch of code) and deployed it as a legacy GitBook to my own GitBook account.

We could, therefore, go back to using legacy version of GitBook and avoid doing a lot of patch-up work, though I am not necessarily recommending this. Otherwise, I'll go back to patching up the books we have to be suitable for the v2 version. Thoughts?

[dlebauer]

Yes - it did explicitly ask if I wanted to upgrade one day when I logged in. It isn't clear to me what key features in v2 require patching (where the current documentation is broken). But v2 is much easier to use. I see a lot of broken links - e.g. to tables - and these are much easier to fix in the new version.

The thing I am confused about is that for v2 it says 'We no longer store Markdown or HTML, instead we store rich JSON data structures.', though the source code on github still appears to be markdown. As long as that is the case I think it is okay to stick with gitbook and move to v2. If that is not the case, then we should stick w/ v1 and consider moving to a different markdown based engine like bookdown which is used by PEcAn.

I'm not sure how long they will support v1, but I'd prefer not to be tied to a less user friendly legacy version of the software. So as long as we can still export to markdown lets go to v2 and it would be great if you could patch it up.

Thanks!

[robkooper]

it is worth it to look at rmarkdown, specifically https://bookdown.org/.

[gsrohde]

'We no longer store Markdown or HTML, instead we store rich JSON data structures.'

It would appear that the GitHub-stored Markdown must get converted to JSON in GitBook's own storage during the synchronization process.

It seems that much of the focus of the GitBook upgrade is to make WYSIWYG online editing easier. My way of working has been, up to now, to clone a copy of the GitHub repository, edit the Markdown and build locally using the GitBook CLI, and then commit and push once things look the way I want, but it appears I'll have to do things differently now.

One nice new feature of the v2 GitBook interface is that you can allow the user to choose which branch to view. Right now, there are two choices—"Primary version" (master) and "gitbook". I don't know if you (@dlebauer) explicitly set "gitbook" as a viewable branch or whether this is a default. (There are two other, not-viewable branches.) But my plan is to use "gitbook" for provisional changes, then make pull requests for merging into the master branch (though I probably won't bother with pull requests for the cleanup work I'm currently doing where I'm not really changing content).

@robkooper: The rmarkdown/bookdown.org option seems like it might be worth pursuing, though I am somewhat reluctant to change our documentation-hosting platform yet once again (we used to use Authorea, and I think maybe we used something else before that). It is somewhat distressing, however, that GitBook would veer off in a new direction like this that will undoubtably break many existing books, and a platform that has the weight of the R community behind it might be less likely to do so. I'm also a bit uncomfortable that there seems to be much with GitBook going on behind the scenes that is poorly documented or not documented at all. But then I suppose I could be accused of being a control freak.

[gsrohde]

@dlebauer I did some cleanup on the gitbook branch, then merged into master. Now, most pages don't display. No error messages or anything. Very frustrating.

[gsrohde]

@dlebauer, @robkooper Because GitBook is being difficult, I decided to go ahead and try bookdown, which uses R Markdown. I deployed a draft of the first few chapters of the BETYdb Technical Documentation here: https://bookdown.org/connect/#/apps/1921/access

To produce this, I used the Markdown files from before GitBook munged all the files by stripping out footnotes, inserting backslashes, and other baffling changes. I made a few minor tweaks to two of the Markdown files and I had to add some R-related files, but I think the result is pretty good. My main disappointment with bookdown is that arranging the table of contents the way I want is more difficult (and I think there is more I would want to do here if we decide to switch), and there was also a bit of a learning curve for the initial setup.

Please let me know what you think. Although there are things I like about GitBook v2, in general I'm finding it very unsatisfactory. For example, although all pages of BETYdb Technical Documentation are now displaying, they are displaying without the changes I made.

[gsrohde]

Seems to be building automatically now, and besides, we're moving to bookdown soon. Closing.