{"id":14988218,"url":"https://github.com/apache/brooklyn-docs","last_synced_at":"2025-04-13T09:51:05.214Z","repository":{"id":2713172,"uuid":"47246079","full_name":"apache/brooklyn-docs","owner":"apache","description":"Mirror of Apache Brooklyn docs","archived":false,"fork":false,"pushed_at":"2025-04-04T06:12:10.000Z","size":29024,"stargazers_count":10,"open_issues_count":5,"forks_count":38,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-10T11:58:34.921Z","etag":null,"topics":["brooklyn","cloud","java"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing/index.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-02T08:00:06.000Z","updated_at":"2025-04-04T06:12:16.000Z","dependencies_parsed_at":"2024-07-23T13:42:08.281Z","dependency_job_id":null,"html_url":"https://github.com/apache/brooklyn-docs","commit_stats":{"total_commits":1530,"total_committers":75,"mean_commits":20.4,"dds":0.6908496732026144,"last_synced_commit":"7b98a908a106fbc3fb6a2f2ece38996b57911875"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fbrooklyn-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fbrooklyn-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fbrooklyn-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fbrooklyn-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/brooklyn-docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248666594,"owners_count":21142271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brooklyn","cloud","java"],"created_at":"2024-09-24T14:16:18.548Z","updated_at":"2025-04-13T09:51:05.191Z","avatar_url":"https://github.com/apache.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Brooklyn Website and Docs Source\n================================\n\nContributor Workflow\n--------------------\n\nThe contributor workflow is identical to that used by the main project, with\npull requests and contributor licenses required. Therefore you should\nfamiliarise yourself with the standard workflow for Apache Brooklyn:\n\n* [Guide for contributors][CONTRIB]\n* [Guide for committers][COMMIT]\n\n[CONTRIB]: https://brooklyn.apache.org/community/how-to-contribute-docs.html\n[COMMIT]: https://brooklyn.apache.org/developers/committers/index.html\n\nThe documents are written in [kramdown](http://kramdown.gettalong.org/syntax.html) a superset of Markdown \nwhich is processed into HTML using [Jekyll](https://jekyllrb.com/). In addition to the standard set of options\nand notation available with these platforms, a number of custom plug-ins have been implemented specifically\nfor the Brooklyn docs. These are detailed in the [contributing to docs](https://brooklyn.apache.org/contributing) doc.  \n\nWorkstation Setup\n-----------------\n\nFirst, if you have not already done so, clone the `brooklyn` repository and subprojects\nand set up the remotes as described in [Guide for committers][COMMIT].\n\nThe Brooklyn documentation uses [Jekyll](https://jekyllrb.com/) to process the site content into HTML. \nThis in turn requires Ruby and gems as described in the `Gemfile`:\ninstall [RVM](http://rvm.io/) to manage Ruby installations and sets of Ruby gems.\n\n    curl -sSL https://get.rvm.io | bash -s stable --auto-dotfiles\n\nClose your shell session and start a new one, to get the new\nenvironment that RVM has configured. Change directory to the location where\nthis project is (where this file is located).\n\nRVM should detect its configuration inside `Gemfile` and try to configure itself. \nMost likely it will report that the required version of Ruby is not installed,\nand it will show the command that you need to run to install the correct version. \nFollow the instructions it shows, typically something like `rvm get master \u0026\u0026 rvm install 3.0.1`.\n\nOnce the correct version of Ruby is installed, change to your home directory\nand then change back (`cd ~ ; cd -`).\nThis will cause RVM to re-load configuration from `Gemfile` with the correct version of Ruby.\n\nFinally, run this command to install all the required Gems \nat the correct versions:\n\n    bundle install\n\nAny time you need to reset your Ruby environment for `jekyll` to run correctly,\ngo to this directory (or the `_build` subdir) and re-run the above command.\n\nOn some platforms there may be some fiddling required before `jekyll` runs without errors,\nbut the ecosystem is fairly mature and most problems can be resolved with a bit of googling.\nSome issues we've encountered are:\n\n * on Mac, install xcode and its command-line tools\n * if ruby gets confused about versions,\n   [clean out your gems](http://judykat.com/ken-judy/force-bundler-rebuild-ruby-rails-gemset/)\n * if `libxml2` fails, set `bundle config build.nokogiri --use-system-libraries` before the install\n   (more details [here](http://www.nokogiri.org/tutorials/installing_nokogiri.html))\n * on Ubuntu, `sudo apt-get install libxslt-dev libxml2-dev libcurl4-openssl-dev python-minimal`\n * if openssl library headers are not found, set the dir explicitly, eg for `eventmachine` try `gem install eventmachine -- --with-openssl-dir=/usr/local/opt/openssl@1.1`\n * if `libv8` complains: `gem install libv8 -- --with-system-v8` or eg `gem install libv8 -v '3.16.14.19' -- --with-system-v8`\n * for rubyracer to find v8: `gem install therubyracer -- --with-v8-dir=/usr/local/opt/v8@3.15`\n    * needs v8 installed by brew as: brew install v8-315\n\n\nIf you are building the PDF documentation, this requires [wkhtmltopdf](http://wkhtmltopdf.org/). \nYou can download it from [here](http://wkhtmltopdf.org/downloads.html) or use the usual apt-get / yum / brew.\n\nSeeing the Website and Docs\n---------------------------\n\nTo build and see most of the documentation, run this command in this folder:\n\n    jekyll serve\n    \nThis will start up a local web server. The URL is printed by Jekyll when the server starts,\ne.g. http://localhost:4000/ . The server will continue to run until you press Ctrl+C.\nModified files will be detected and regenerated (but that might take up to 1m).\nAdd `--no-watch` argument to turn off regeneration, or use `jekyll build` instead\nto generate a site in `_site` without a server.\n\nThis does \u003ci\u003enot\u003c/i\u003e generate API docs and certain other material;\nsee the notes on `_build/build.sh` below for that.\n\n\nProject Structure\n-----------------\n\nNote that there are two interlinked micro-sites in this project:\n\n* `/website`: this contains the main Brooklyn website, including committer instructions,\n  download instructions, and \"learn more\" pages;\n  this content has **only one instance** on the live website,\n  and as changes are published they replace old content\n  \n* `/guide`: this contains the user guide and information pertaining to a \n  specific Brooklyn version, including code structure and API documentation;\n  the live website contains a **copy of the guide for each Brooklyn version**,\n  with the code coming from the corresponding branch in `git`\n\nIn addition note the following folders:\n\n* `/style`: contains JS, CSS, and image resources;\n  on the live website, this folder is installed at the root *and* \n  into archived versions of the guide. \n  \n* `/_build`: contains build scripts and configuration files,\n  and tests for some of the plugins\n\n* `/_plugins`: contains Jekyll plugins which supply tags and generation\n  logic for the sites, including links and tables of contents\n\n* `/_layouts`: contains HTML templates used by pages\n\n* `/_includes`: contains miscellaneous content used by templates and pages\n\nJekyll automatically excludes any file or folder beginning with `_`\nfrom direct processing, so these do *not* show up in the `_site` folder\n(except where they are embedded in other files).  \n\n**A word on branches:**  The `/website` folder can be built against any branch;\ntypically changes are made and published from `master`, to ensure that all versions\nare listed correctly.\nIn contrast the `/guide` folder should be updated and built against the branch for which \ninstructions are being made, e.g. `master` for latest snapshot updates, \nor `0.7.0-M2` for that milestone release.\nIt *is* permitted to make changes to docs (and docs only!) after a release has\nbeen made. In most cases, these changes should also be made to master.\n\n\nWebsite Structure\n-----------------\n\nThe two micro-sites above are installed on the live website as follows:\n\n* `/`: contains the website\n* `/v/\u003cversion\u003e`: contains specific versions of the guide,\n  with the special folder `/v/latest` containing the recent preferred stable/milestone version \n\nThe site itself is hosted at `brooklyn.apache.org` with a `CNAME`\nrecord from `brooklyn.io`.\n\nContent is published to the site by updating an \nApache subversion repository, `brooklyn-site-public` at\n`https://svn.apache.org/repos/asf/brooklyn/site`.\nSee below for more information.\n\n\nBuilding the Website and Guide\n------------------------------\n\nFor most users, the `jekyll serve` command described above is sufficient to test changes locally.\nThe main reason to use the build scripts (and to read this section) is to push changes to the server\n(requires Apache Brooklyn commit rights), or to test generated content such as API docs.\n\nThe build is controlled by config files in `_build/` and accessed through `_build/build.sh`.\nThere are a number of different builds possible; to list these, run:\n\n    _build/build.sh help\n\nThe normal build outputs to `_site/`.  The three builds which are most relevant to updating the live site are:\n\n* **website-root**: to build the website only, in the root\n* **guide-latest**: to build the guide only, in `/v/latest/`\n* **guide-version**: to build the guide only, in the versioned namespace e.g. `/v/\u003cversion\u003e/`\n\nThere are some others, including `test-both`, which apply slightly different configurations\nuseful for testing.\nSupported options beyond that include `--serve`, to start a web browser serving the content of `_site/`,\nand `--skip-javadoc`, to speed up the build significantly by skipping javadoc generation.\nA handy command for testing the live files, analogous to `jekyll serve` \nbut with the correct file structure, and then checking links, is:\n\n    _build/build.sh test-both --skip-javadoc --serve\n\nAnd to run link-checks quickly (without validating external links), use:\n\n    htmlproof --href_ignore \"https?://127.*\" --alt_ignore \".*\" --disable_external _site\n\n\n\nPreparing for a Release\n-----------------------\n\nWhen doing a release and changing versions:\n\n* Before branching:\n  * Change the `brooklyn-stable-version` variable in `_config.yml`\n  * Update `website/meta/versions.md` with a bit of info on this release\n*  In the branch, with `change-version.sh` run (e.g. from `N.SNAPSHOT` to `N`)\n  * Ensure the `guide/start/release-notes.md` file is current\n  * Build and publish `website-root`, `guide-latest`, and `guide-version`\n* In master, with `change-version.sh` run (e.g. to `N+1-SNAPSHOT`)\n  * Clear old stuff in the `guide/start/release-notes.md` file\n  * Optionally build and public `guide-version`\n \n\nPublishing the Website and Guide\n--------------------------------\n\nThe Apache website publication process is based around the Subversion repository; \nthe generated HTML files must be checked in to Subversion, whereupon an automated process \nwill publish the files to the live website.\nSo, to push changes the live site, you will need to have the website directory checked out \nfrom the Apache subversion repository. We recommend setting this up as a sibling to your\n`brooklyn` git project directory:\n\n    # verify we're in the right location and the site does not already exist\n    ls _build/build.sh || { echo \"ERROR: you should be in the docs/ directory to run this command\" ; exit 1 ; }\n    ls ../../brooklyn-site-public \u003e /dev/null \u0026\u0026 { echo \"ERROR: brooklyn-site-public dir already exists\" ; exit 1 ; }\n    pushd `pwd -P`/../..\n    \n    svn --non-interactive --trust-server-cert co https://svn.apache.org/repos/asf/brooklyn/site brooklyn-site-public\n    \n    # verify it\n    cd brooklyn-site-public\n    ls style/img/apache-brooklyn-logo-244px-wide.png || { echo \"ERROR: checkout is wrong\" ; exit 1 ; }\n    export BROOKLYN_SITE_DIR=`pwd`\n    popd\n    echo \"SUCCESS: checked out site in $BROOKLYN_SITE_DIR\"\n\nWith this checked out, the `build.sh` script can automatically copy generated files into the right subversion sub-directories\nwith the `--install` option.  (This assumes the relative structure described above; if you have a different\nstructure, set BROOKLYN_SITE_DIR to point to the directory as above.  Alternatively you can copy files manually,\nusing the instructions in `build.sh` as a guide.)\n\nA typical update consists of the following commands (or a subset),\ncopied to `${BROOKLYN_SITE_DIR-../../brooklyn-site-public}`:\n\n    # ensure svn repo is up-to-date (very painful otherwise)\n    cd ${BROOKLYN_SITE_DIR-../../brooklyn-site-public}\n    svn up\n    cd -\n\n    # versioned guide, safe for snapshots, relative to /v/\u003cversion\u003e/\n    _build/build.sh guide-version --install\n\n    # main website, if desired, relative to / \n    _build/build.sh website-root --install\n    \n    # this version as the latest guide, if desired, relative to /v/latest/\n    _build/build.sh guide-latest --install\n    \n(If HTML-Proofer find failures, then fix the links etc. Unfortunately, the javadoc build \ngives a lot of warnings. Fixing those is not part of this activity).\n\nYou can then preview the public site of [localhost:4000](http://localhost:4000) with:\n\n    _build/serve-public-site.sh\n\nNext it is recommended to go to the SVN dir and \nreview the changes using the usual `svn` commands -- `status`, `diff`, `add`, `rm`, etc.\nNote in particular that deleted files need special attention (there is no analogue of\n`git add -A`!). Look at deletions carefully, to try to avoid breaking links, but once\nyou've done that these commands might be useful:\n\n    cd ${BROOKLYN_SITE_DIR-../../brooklyn-site-public}\n    svn add * --force\n    export DELETIONS=$( svn status | sed -e '/^!/!d' -e 's/^!//' )\n    if [ ! -z \"${DELETIONS}\" ] ; then svn rm ${DELETIONS} ; fi\n\nThen check in the changes (probably picking a better message than shown here):\n\n    svn ci -m 'Update Brooklyn website'\n\nThe changes should become live within a few minutes.\n\nSVN commits can be **slow**, particularly if you've regenerated javadoc.\n(The date is included in all javadoc files so the commands above will cause *all* javadoc to be updated.)\nUse `_build/build.sh guide-version --install --skip-javadoc` to update master while re-using the previously installed javadoc.\nThat command will fail if javadoc has not been generated for that version.\n\n\nMore Notes on the Code\n----------------------\n\n# Plugins\n\nWe use some custom Jekyll plugins, in the `_plugins` dir:\n\n* include markdown files inside other files (see, for example, the `*.include.md` files \n  which contain text which is used in multiple other files)\n  * `read_jekyll` will read a file and jekyll-process it (eg for nested `{% ... readj ` calls;\n    it's just like `include_relative` but with two differences: when `readj` is used\n    nested `read_jekyll` calls are relative to the included file where it is contained,\n    rather than relative to the root md file which made the first `read_jekyll` call\n    (so in general it's more intuitive than `include_relative`),\n    and `include_relative` processes front matter whereas `read_jekyll` mangles it\n  * `read_literal` is like `read_jekyll` but without the jekyll/tag processing\n  * `read` will autodetect based on filename -- jekyll for `*.md` and literal for all others\n* generate the site structure / menu objects\n* parse JSON which we can loop over in our markdown docs (to build up models; previously used\n  for the TOC in the guide, but now replaced with site_structure)\n* trim whitespace of ends of variables\n\n\n# Versions\n\nArchived versions are kept under `/v/` in the website.  New versions should be added with\nthe appropriate directory (`_build/build.sh guide-version` above will do this).  \nThese versions take their own copy of the `style` files so that changes there will not affect future versions.\n\nA list of available versions is in `website/meta/versions.md`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fbrooklyn-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Fbrooklyn-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fbrooklyn-docs/lists"}