merlimat closed pull request #1939: Instructions to build site on linux without root URL: https://github.com/apache/incubator-pulsar/pull/1939
This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/site/README.md b/site/README.md index 26974d2c66..6f96a46454 100644 --- a/site/README.md +++ b/site/README.md @@ -37,9 +37,9 @@ This website is built using a wide range of tools. The most important among them ## Requirements and setup -> **Note**: at the moment, running the site locally *may* work on Linux but the site setup has been built with MacOS in mind. We will provide better cross-platform support in the near future. +### MacOS -To build and run the site locally, you need to have Ruby 2.4.1 installed and set as the Ruby version here in the `site` directory. You can install and set the Ruby version using [rvm](https://rvm.io): +To build and run the site locally, you need to have Ruby 2.3.1 installed and set as the Ruby version here in the `site` directory. You can install and set the Ruby version using [rvm](https://rvm.io): ```bash $ cd site @@ -53,6 +53,45 @@ Then you can install all Ruby dependencies, as well as [Doxygen](http://www.stac $ make setup ``` +### Linux + +**NOTE**: These instruction have been tested with Ubuntu 16.04 and Debian Stretch. YMMV with other distributions. + +The site is built using Ruby 2.3.1. Neither Ubuntu nor Debian have this in their repositories, so it must be installed via RVM. Instructions for RVM installation are available [here](https://rvm.io/rvm/install). When RVM is installed, it will ask you to "source" a script. You can either add this to your .bashrc, or source it every time you build the the site. Once you have done so, install ruby-2.3.1. + +```bash +$ source /usr/share/rvm/scripts/rvm +$ rvm install ruby-2.4.1 +``` + +Doxygen, pdoc and pygments are required to build the C++ and python documentation. Pdoc and pygments are not in the Ubuntu/Debian repos. The best way to install them is in a virtualenv to avoid polluting your system packages. + +```bash +$ sudo apt-get install doxygen python-virtualenv +$ virtualenv ~/pulsar-site-venv +$ source ~/pulsar-site-venv/bin/activate +(pulsar-site-venv) $ pip install pdoc pygments +``` + +Once all the dependencies are installed, change into the site directory and run setup to install all the required ruby gems. + +```bash +(pulsar-site-venv) $ cd site +(pulsar-site-venv) $ rvm use . +(pulsar-site-venv) $ make setup +``` + +## Building the site + +To build the site, run the build make target. If you are running in linux, you should do this on a terminal which has both the venv and rvm activated. + +```bash +$ source ~/pulsar-site-venv/bin/activate # linux only +$ source /usr/share/rvm/scripts/rvm #linux only +$ cd site +$ make build +``` + ## Running the site locally To run the site locally: diff --git a/site/scripts/python-doc-gen.sh b/site/scripts/python-doc-gen.sh index cacea1bcfd..ea745b70eb 100755 --- a/site/scripts/python-doc-gen.sh +++ b/site/scripts/python-doc-gen.sh @@ -18,6 +18,7 @@ # under the License. # +set -xe ROOT_DIR=$(git rev-parse --show-toplevel) @@ -25,9 +26,10 @@ ROOT_DIR=$(git rev-parse --show-toplevel) # so that Pdoc can import the module pip install pulsar-client -INPUT=$ROOT_DIR/pulsar-client-cpp/python/pulsar.py DESTINATION=$ROOT_DIR/site/api/python -PYTHONPATH=$ROOT_DIR/pulsar-client-cpp/python pdoc $INPUT \ +rm -fr $DESTINATION/{index.html,functions,pulsar} +PYTHONPATH=$ROOT_DIR/pulsar-client-cpp/python pdoc pulsar \ --html \ --html-dir $DESTINATION -mv $DESTINATION/pulsar.m.html $DESTINATION/index.html +mv -f $DESTINATION/pulsar/* $DESTINATION/ +rmdir $DESTINATION/pulsar ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
