New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature/geode 1952 2 #259

Merged
merged 13 commits into from Oct 14, 2016

Conversation

Projects
None yet
7 participants
@joeymcallister
Contributor

joeymcallister commented Oct 13, 2016

This merges feature/GEODE-1952, which was branched from the
docs donation staging branch, into feature/GEODE-1952-2, which
was branched from develop.

In addition to merging the docs donation, it adds the
geode-book directory for building the end-user documentation
from the content in the geode-docs directory. It also updates the
geode-docs README for building the docs locally.

@sbawaska

This comment has been minimized.

Show comment
Hide comment
@sbawaska

sbawaska Oct 13, 2016

Contributor

Hi @joeymcallister The CI failed because the new files are missing the Apache License header. Can you please fix this and re-submit the pull request?

71 Unknown Licenses
*******************************
Unapproved licenses:
  /home/travis/build/apache/incubator-geode/geode-book/Gemfile
  /home/travis/build/apache/incubator-geode/geode-book/Gemfile.lock
  /home/travis/build/apache/incubator-geode/geode-book/config.yml
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/index.html.erb
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/book.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/waypoints/context.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/waypoints/group.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/waypoints/noframeworkAdapter.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/waypoints/sticky.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/waypoints/waypoint.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/layouts/_book-footer.erb
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/layouts/_title.erb
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/stylesheets/book-styles.css.scss
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/stylesheets/partials/_book-base-values.scss
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/stylesheets/partials/_book-vars.scss
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/subnavs/geode-subnav.erb
  /home/travis/build/apache/incubator-geode/geode-book/redirects.rb
  /home/travis/build/apache/incubator-geode/geode-docs/images_svg/JMX_Architecture.svg
  /home/travis/build/apache/incubator-geode/geode-docs/images_svg/MBeans.svg
...
Contributor

sbawaska commented Oct 13, 2016

Hi @joeymcallister The CI failed because the new files are missing the Apache License header. Can you please fix this and re-submit the pull request?

71 Unknown Licenses
*******************************
Unapproved licenses:
  /home/travis/build/apache/incubator-geode/geode-book/Gemfile
  /home/travis/build/apache/incubator-geode/geode-book/Gemfile.lock
  /home/travis/build/apache/incubator-geode/geode-book/config.yml
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/index.html.erb
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/book.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/waypoints/context.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/waypoints/group.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/waypoints/noframeworkAdapter.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/waypoints/sticky.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/javascripts/waypoints/waypoint.js
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/layouts/_book-footer.erb
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/layouts/_title.erb
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/stylesheets/book-styles.css.scss
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/stylesheets/partials/_book-base-values.scss
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/stylesheets/partials/_book-vars.scss
  /home/travis/build/apache/incubator-geode/geode-book/master_middleman/source/subnavs/geode-subnav.erb
  /home/travis/build/apache/incubator-geode/geode-book/redirects.rb
  /home/travis/build/apache/incubator-geode/geode-docs/images_svg/JMX_Architecture.svg
  /home/travis/build/apache/incubator-geode/geode-docs/images_svg/MBeans.svg
...
@metatype

This comment has been minimized.

Show comment
Hide comment
@metatype

metatype Oct 13, 2016

Contributor

Is geode-book a generated dir or a source directory?

Contributor

metatype commented Oct 13, 2016

Is geode-book a generated dir or a source directory?

@joeymcallister

This comment has been minimized.

Show comment
Hide comment
@joeymcallister

joeymcallister Oct 13, 2016

Contributor

geode-book is a source directory containing the pieces (e.g., the
config.yml that points Bookbinder to content, and the geode-subnav.erb
that provides the book's table of contents) that Bookbinder uses to
generate directories geode-book/output/ and geode-book/final_app from
the markdown files in geode-docs.

On Thu, Oct 13, 2016 at 1:44 PM Anthony Baker notifications@github.com
wrote:

Is geode-book a generated dir or a source directory?


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#259 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/APXEUTUuhqkV-oHKwTUCuOLUm8zUxP1bks5qzpg7gaJpZM4KVYQ9
.

Contributor

joeymcallister commented Oct 13, 2016

geode-book is a source directory containing the pieces (e.g., the
config.yml that points Bookbinder to content, and the geode-subnav.erb
that provides the book's table of contents) that Bookbinder uses to
generate directories geode-book/output/ and geode-book/final_app from
the markdown files in geode-docs.

On Thu, Oct 13, 2016 at 1:44 PM Anthony Baker notifications@github.com
wrote:

Is geode-book a generated dir or a source directory?


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#259 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/APXEUTUuhqkV-oHKwTUCuOLUm8zUxP1bks5qzpg7gaJpZM4KVYQ9
.

@davebarnes97

This comment has been minimized.

Show comment
Hide comment
@davebarnes97

davebarnes97 Oct 13, 2016

Contributor

+1
Bookbinder publishing procedure worked for me.

Contributor

davebarnes97 commented Oct 13, 2016

+1
Bookbinder publishing procedure worked for me.

@joeymcallister

This comment has been minimized.

Show comment
Hide comment
@joeymcallister

joeymcallister Oct 13, 2016

Contributor

@sbawaska Commit 2b6fec8 corrects the license issues and I was able to build successfully.

Contributor

joeymcallister commented Oct 13, 2016

@sbawaska Commit 2b6fec8 corrects the license issues and I was able to build successfully.

@karensmolermiller

This comment has been minimized.

Show comment
Hide comment
@karensmolermiller

karensmolermiller Oct 13, 2016

Contributor

+1
I built with bookbinder and viewed with rackup, per the README.md instructions.
Running ./gradlew rat passed the license check: no licensing issues.

Contributor

karensmolermiller commented Oct 13, 2016

+1
I built with bookbinder and viewed with rackup, per the README.md instructions.
Running ./gradlew rat passed the license check: no licensing issues.

@upthewaterspout

Add the final_app and output directories to the rat excludes, so people don't have rat failures after building the docs.

Is there a clean target to remove the docs?

Show outdated Hide outdated geode-docs/README.md
@metatype

This comment has been minimized.

Show comment
Hide comment
@metatype

metatype Oct 14, 2016

Contributor

I think the README could use a few clarifications:

  1. You also need to run bundle install in the final_app dir.
  2. How do we take the generated html site and merge it into the asf-site branch so it can be hosted on geode.apache.org.

I also ran into some strange ruby errors installing libv8 / therubyracer that required google's help.

Contributor

metatype commented Oct 14, 2016

I think the README could use a few clarifications:

  1. You also need to run bundle install in the final_app dir.
  2. How do we take the generated html site and merge it into the asf-site branch so it can be hosted on geode.apache.org.

I also ran into some strange ruby errors installing libv8 / therubyracer that required google's help.

@upthewaterspout

This comment has been minimized.

Show comment
Hide comment
@upthewaterspout

upthewaterspout Oct 14, 2016

Contributor

I think geode-docs should be a subdirectory of geode-book so we don't have two unrelated directories for these docks.

It should probably output to a directory called build to be consistent with the rest of the build.

Contributor

upthewaterspout commented Oct 14, 2016

I think geode-docs should be a subdirectory of geode-book so we don't have two unrelated directories for these docks.

It should probably output to a directory called build to be consistent with the rest of the build.

@joeymcallister

This comment has been minimized.

Show comment
Hide comment
@joeymcallister

joeymcallister Oct 14, 2016

Contributor

@upthewaterspout Bookbinder requires the "book" directory to be at the same dir level as the content, so a subdirectory wouldn't work here. If the goal is to clean up the top level, we could move both of these directories into one directory—perhaps as follows:

  • geode-docs
    • geode-docs-book
    • geode-docs-content
Contributor

joeymcallister commented Oct 14, 2016

@upthewaterspout Bookbinder requires the "book" directory to be at the same dir level as the content, so a subdirectory wouldn't work here. If the goal is to clean up the top level, we could move both of these directories into one directory—perhaps as follows:

  • geode-docs
    • geode-docs-book
    • geode-docs-content
@joeymcallister

This comment has been minimized.

Show comment
Hide comment
@joeymcallister

joeymcallister Oct 14, 2016

Contributor

@metatype

  1. Running bundle install in the final_app dir isn't something I'm familiar with. We don't usually have to do it, and I'm currently able to build and rackup the Geode book without doing that but, well ... who knows what Ruby's doing behind the scenes? (@upthewaterspout Did you happen to encounter this when running through the process the first time?)
  2. I postponed the docs-to-website step in order to focus on getting the docs buildable and licensed. The short version is that you can move the contents of the directory geode-book/final_app/public/docs to the directory geode-site/website/content/docs and then follow the instructions for updating the website located at geode-site/website/README.md. (I need to tweak some stylesheet stuff in geode-site to make the docs display correctly, but that should be a one-time thing.)
Contributor

joeymcallister commented Oct 14, 2016

@metatype

  1. Running bundle install in the final_app dir isn't something I'm familiar with. We don't usually have to do it, and I'm currently able to build and rackup the Geode book without doing that but, well ... who knows what Ruby's doing behind the scenes? (@upthewaterspout Did you happen to encounter this when running through the process the first time?)
  2. I postponed the docs-to-website step in order to focus on getting the docs buildable and licensed. The short version is that you can move the contents of the directory geode-book/final_app/public/docs to the directory geode-site/website/content/docs and then follow the instructions for updating the website located at geode-site/website/README.md. (I need to tweak some stylesheet stuff in geode-site to make the docs display correctly, but that should be a one-time thing.)
@joeymcallister

This comment has been minimized.

Show comment
Hide comment
@joeymcallister

joeymcallister Oct 14, 2016

Contributor

@upthewaterspout:

Add the final_app and output directories to the rat excludes, so people don't have rat failures after building the docs.

Excellent suggestion. Thank you. 👍

Is there a clean target to remove the docs?

My experience with this has always been with a dedicated docs-book repo, so git clean was sufficient. If there's a way to specifically clean only the geode-book dir, I'd love to implement it.

Contributor

joeymcallister commented Oct 14, 2016

@upthewaterspout:

Add the final_app and output directories to the rat excludes, so people don't have rat failures after building the docs.

Excellent suggestion. Thank you. 👍

Is there a clean target to remove the docs?

My experience with this has always been with a dedicated docs-book repo, so git clean was sufficient. If there's a way to specifically clean only the geode-book dir, I'd love to implement it.

@upthewaterspout

This comment has been minimized.

Show comment
Hide comment
@upthewaterspout

upthewaterspout Oct 14, 2016

Contributor

@joeymcallister - Ok, the parallel directories makes more sense now. We can always move stuff around after 1.0 if we decide to.

I also had to do bundle install in the final_app directory in order to run rackup. I don't know if we really need to use rackup anyway, this seems like an easier way to quickly view the book:

cd final_app/public
python -m SimpleHTTPServer 8080
Contributor

upthewaterspout commented Oct 14, 2016

@joeymcallister - Ok, the parallel directories makes more sense now. We can always move stuff around after 1.0 if we decide to.

I also had to do bundle install in the final_app directory in order to run rackup. I don't know if we really need to use rackup anyway, this seems like an easier way to quickly view the book:

cd final_app/public
python -m SimpleHTTPServer 8080
@joeymcallister

This comment has been minimized.

Show comment
Hide comment
@joeymcallister

joeymcallister Oct 14, 2016

Contributor

Tweaked the build instructions to include build install before rackup. Also moved the README, which focuses on building the docs, to the geode-book dir (and pointed to it from geode-docs/CONTRIBUTE.md, which focuses on working with the raw content).

If it's okay with everyone, I'd like to call GEODE-1952 done and revisit any outstanding issues from the thread (e.g., dir structure) in future work/tickets.

Contributor

joeymcallister commented Oct 14, 2016

Tweaked the build instructions to include build install before rackup. Also moved the README, which focuses on building the docs, to the geode-book dir (and pointed to it from geode-docs/CONTRIBUTE.md, which focuses on working with the raw content).

If it's okay with everyone, I'd like to call GEODE-1952 done and revisit any outstanding issues from the thread (e.g., dir structure) in future work/tickets.

@metatype

This comment has been minimized.

Show comment
Hide comment
@metatype

metatype Oct 14, 2016

Contributor

LGTM

Contributor

metatype commented Oct 14, 2016

LGTM

@upthewaterspout

This comment has been minimized.

Show comment
Hide comment
@upthewaterspout

upthewaterspout Oct 14, 2016

Contributor

+1

Contributor

upthewaterspout commented Oct 14, 2016

+1

@asfgit asfgit merged commit 742d306 into apache:feature/GEODE-1952-2 Oct 14, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment