You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by bostko <gi...@git.apache.org> on 2015/02/21 23:05:19 UTC
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
GitHub user bostko opened a pull request:
https://github.com/apache/incubator-brooklyn/pull/524
Catalog documentation improvements
* Include the header in the catalog pages
* Load an entity using one html file
Simplify the build
* Delete the separate configuration file for the catalog
* Move the catalog js and catalog css to the js folder
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/bostko/incubator-brooklyn catalog-documentation-improvements
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-brooklyn/pull/524.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #524
----
commit 671fda387c445726cb96d468d056c6923a6a3c10
Author: Valentin Aitken <bo...@gmail.com>
Date: 2015-02-20T18:09:05Z
- Catalog rearrangement so it work with jekyll serve without moving files
- Include the Navigation menu in the catalog
commit cbe6f8e6f1affffea39ea87fe9fd89d887219f16
Author: Valentin Aitken <bo...@gmail.com>
Date: 2015-02-21T22:00:35Z
Catalog items
Load an entity using one html file
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#discussion_r26608478
--- Diff: docs/_config.yml ---
@@ -26,7 +26,8 @@ url_root: http://0.0.0.0:4000
path:
style: /style
guide: /guide
- website: /website
+ #guide: "/v/latest"
--- End diff --
aha i see why you did what you did -- but it needs to be reverted.
we like to be able to run `jekyll serve` from the root and for the resulting links to be happy. this means we have to have guide in guide and website it website. this is why the structural changes are done afterwards production builds. unfortunate but i don't see a way around it.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#discussion_r26608263
--- Diff: docs/_build/build.sh ---
@@ -90,7 +90,7 @@ function parse_mode() {
SUMMARY="user guide files in the root"
;;
test-both)
- JEKYLL_CONFIG=_config.yml,_build/config-production.yml,_build/config-exclude-root-index.yml,_build/config-website-root.yml,_build/config-guide-latest.yml
+ JEKYLL_CONFIG=_config.yml,_build/config-production.yml,_build/config-exclude-root-index.yml,_build/config-guide-latest.yml
--- End diff --
again i think this was correct, and it was working when it was written. can you back out these changes and let's discuss?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#issuecomment-82562523
a few things to revert on the docs build process but otherwise looks very good
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by bostko <gi...@git.apache.org>.
Github user bostko commented on the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#issuecomment-87226883
@ahgittin In order to simplify the build I removed the `docs/_build/config-website-root.yml`
and I removed the guide path `/v/latest`
My idea is to use one centralized place for configuration `_config.yml`. This simplifies a lot the development since now you have to move the compiled files from the website folder to the docs root.
Differentiating the jekyll configs leads to а lot of different folders and configs and if some link is not working or if there is some other problem it is harder to debug.
I see the point about versioning the docs and putting them in separate folders /v/latest/guide
but I think it is easier if we do docs versioning as a whole and put everything in /v/version not only the guide. The thing which is still more updateble is the catalog_items.json
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#discussion_r26608345
--- Diff: docs/_build/config-website-root.yml ---
@@ -1,3 +0,0 @@
-path:
- website: ""
- guide: "/v/latest"
--- End diff --
as above, let's keep for now and discuss separately
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by neykov <gi...@git.apache.org>.
Github user neykov commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#discussion_r25147624
--- Diff: docs/website/learnmore/catalog/brooklyn-node.html ---
@@ -0,0 +1,90 @@
+---
--- End diff --
brooklyn-node refers to the specific `brooklyn.entity.brooklynnode.BrooklynNode` entity. `item.html` as in `Catalog item` would be more appropriate.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by bostko <gi...@git.apache.org>.
Github user bostko commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#discussion_r25154244
--- Diff: docs/style/js/catalog/common.js ---
@@ -25,7 +25,7 @@ var brooklyn = (function ($, _) {
},
entityCard: _.template(
- "<a class='plain' data-type='<%= type %>' href='entities/<%= type %>.html'>" +
+ "<a class='plain' data-type='<%= type %>' href='brooklyn-node.html#entities/<%= type %>'>" +
--- End diff --
Yes you are right about the SEO. Generally it is not good to have Ajax requests in the first place.
Although it is not recognized well in google the catalog classes are listed in google https://www.google.bg/?q=brooklynnode
In order to mimic the current SEO capabilities of the website we have to support https://developers.google.com/webmasters/ajax-crawling/docs/getting-started
_escaped_fragment_ get parameter on the server.
I will research this more if it is possible to use this get_parameter without implementing it on the server and rather use the capabilities of the modern browsers like pushState.
The other option is to autogenerate sitemap.xml
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#issuecomment-90858989
looks good now, thanks @bostko . i've reinstated `docs/index.md` which is useful when running `jekyll serve`, and merged.
a few things it would be nice to clean up:
* search is only on entities and only matches simple class name; should match much more
* hover on an entry shifts the div by a pixel or two; it should highlight only but not shift
* once you've selected an item there is no obvious way to return to the catalog
trivial though, i've merged. great to have this catalog tidied up!
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by bostko <gi...@git.apache.org>.
Github user bostko commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#discussion_r25153850
--- Diff: docs/website/learnmore/catalog/brooklyn-node.html ---
@@ -0,0 +1,90 @@
+---
--- End diff --
Thank you!
I renamed it.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#issuecomment-87343297
of course it would be much simpler if we could simply version everything but we've had this discussion and the consensus was that we needed something like this. it simply doesn't make sense to have old verisons of things like contact information, news pages, community info kicking around, hence the separation into one section which is versioned ("`guide`") and one section which is not ("`website`").
please revert those -- they don't belong in a PR about the catalog in any case!
btw previously this was handled by having two separate projects but that was even more complex as we had different JS versions and builds so i genuinely think this is the least of all evils given the requirement not to have old versions of contact info etc!
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by bostko <gi...@git.apache.org>.
Github user bostko commented on the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#issuecomment-90859642
I added this to my todos, thank you
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/incubator-brooklyn/pull/524
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#discussion_r26608490
--- Diff: docs/_plugins/site_structure.rb ---
@@ -116,7 +116,17 @@ def self.find_page_with_path_absolute_or_relative_to(site, path, referrent, stru
# Pathname API ignores first arg below if second is absolute
# puts "converting #{path} wrt #{referrent ? referrent.path : ""}"
file = Pathname.new(File.dirname(referrent ? referrent.path : "")) + path
- file += "index.md" if file.to_s.end_with? "/"
--- End diff --
much better
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#discussion_r26608208
--- Diff: docs/_build/build.sh ---
@@ -43,7 +43,7 @@ function parse_mode() {
help
exit 0 ;;
website-root)
- JEKYLL_CONFIG=_config.yml,_build/config-production.yml,_build/config-exclude-guide.yml,_build/config-website-root.yml
+ JEKYLL_CONFIG=_config.yml,_build/config-production.yml,_build/config-exclude-guide.yml
--- End diff --
`website-root` should include the config for website root, shouldn't it?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Catalog documentation improvement...
Posted by neykov <gi...@git.apache.org>.
Github user neykov commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/524#discussion_r25147566
--- Diff: docs/style/js/catalog/common.js ---
@@ -25,7 +25,7 @@ var brooklyn = (function ($, _) {
},
entityCard: _.template(
- "<a class='plain' data-type='<%= type %>' href='entities/<%= type %>.html'>" +
+ "<a class='plain' data-type='<%= type %>' href='brooklyn-node.html#entities/<%= type %>'>" +
--- End diff --
Not an expert in SEO, but wouldn't this hamper findability? Technically it makes more sense, but having a separate page for each entity might be more appropriate google-wise.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---