From 72675f5b429dec98499c1d2ca4d5dd6469d9d12b Mon Sep 17 00:00:00 2001 From: Christopher Warrington Date: Mon, 17 Oct 2016 15:24:12 -0700 Subject: [PATCH] Move logo to above the table of contents * Logo is now embedded in the template and above the table of contents * Move logo in README to be at the top and separated with a hr. This looks okay when rendered by GitHub and when rendered by Pandoc. * README.md has gotten long enough that it can use a table of contents * Use inline bash syntax highlighting for README.md: this doesn't highlight extra things like the python mode was doing, and looks reasonable for all the snippets, including the Windows CMD snippets * This also lets us to get rid of the index.html template--it was almost identical to the default.html template, but had some formatting colors overridden to black. Closes https://github.com/Microsoft/bond/pull/237 --- README.md | 148 +++++++++++++++++---------- doc/.pandoc/templates/default.html | 25 ++--- doc/.pandoc/templates/index.html | 154 ----------------------------- doc/CMakeLists.txt | 8 +- doc/src/bond_comm.md | 3 - doc/src/bond_comm_epoxy.md | 3 - doc/src/bond_comm_epoxy_wire.md | 3 - doc/src/bond_comm_roadmap.md | 3 - doc/src/bond_comm_simpleinmem.md | 3 - doc/src/bond_cpp.md | 3 - doc/src/bond_cs.md | 3 - doc/src/bond_py.md | 3 - doc/src/compiler.md | 3 - doc/src/reference_index.md | 3 - doc/src/why_bond.md | 3 - 15 files changed, 110 insertions(+), 258 deletions(-) delete mode 100644 doc/.pandoc/templates/index.html diff --git a/README.md b/README.md index af535e5c..6f71c281 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ +![The Bond logo: a stylized glue gun](https://raw.githubusercontent.com/Microsoft/bond/master/doc/src/logos/bond-logo-64x64-white.png) +
+ [![Build Status](https://travis-ci.org/Microsoft/bond.svg?branch=master)](https://travis-ci.org/Microsoft/bond) [![Bond.CSharp NuGet package](https://img.shields.io/nuget/v/Bond.CSharp.svg?style=flat)](https://Microsoft.github.io/bond/manual/bond_cs.html#nuget-packages) # Bond -![The Bond logo: a stylized glue gun](https://raw.githubusercontent.com/Microsoft/bond/master/doc/src/logos/bond-logo-64x64-white.png) Bond is an open source, cross-platform framework for working with schematized data. It supports cross-language serialization/deserialization and powerful generic mechanisms for efficiently manipulating data. Bond is broadly used at @@ -37,7 +39,9 @@ For a discussion how Bond compares to similar frameworks see [Why Bond](https:// The Bond repository uses Git submodules and should be cloned with the `--recursive` flag: - git clone --recursive https://github.com/Microsoft/bond.git +```bash +git clone --recursive https://github.com/Microsoft/bond.git +``` In order to build Bond you will need CMake (2.8.12+), Haskell (ghc 7.4+ and cabal-install 1.18+) and Boost (1.54+). The core Bond C++ library can be used @@ -54,25 +58,29 @@ version of Clang as it's much faster with template-heavy code like Bond. Run the following commands to install the minimal set of packages needed to build the core Bond library on Ubuntu 14.04: - sudo apt-get install \ - clang \ - cmake \ - zlib1g-dev \ - ghc \ - cabal-install \ - libboost-dev \ - libboost-thread-dev +```bash +sudo apt-get install \ + clang \ + cmake \ + zlib1g-dev \ + ghc \ + cabal-install \ + libboost-dev \ + libboost-thread-dev - cabal update - cabal install cabal-install +cabal update +cabal install cabal-install +``` In the root `bond` directory run: - mkdir build - cd build - cmake .. - make - sudo make install +```bash +mkdir build +cd build +cmake .. +make +sudo make install +``` The `build` directory is just an example. Any directory can be used as the build destination. @@ -80,18 +88,22 @@ destination. In order to build all the C++ and Python tests and examples, a few more packages are needed: - sudo apt-get install \ - python2.7-dev \ - libboost-date-time-dev \ - libboost-test-dev \ - libboost-python-dev +```bash +sudo apt-get install \ + python2.7-dev \ + libboost-date-time-dev \ + libboost-test-dev \ + libboost-python-dev - cabal install happy +cabal install happy +``` Running the following command in the build directory will build and execute all the tests and examples: - make --jobs 8 check +```bash +make --jobs 8 check +``` (The unit tests are large so you may want to run 4-8 build jobs in parallel, assuming you have enough memory.) @@ -101,49 +113,63 @@ assuming you have enough memory.) Install Xcode and then run the following command to install the required packages using Homebrew ([http://brew.sh/](http://brew.sh/)): - brew install \ - cmake \ - ghc \ - cabal-install \ - boost \ - boost-python +```bash +brew install \ + cmake \ + ghc \ + cabal-install \ + boost \ + boost-python +``` (boost-python is optional and only needed for Python support.) Update the cabal package database and install `happy` (only needed for tests): - cabal update - cabal install happy +```bash +cabal update +cabal install happy +``` Bond can be built on OS X using either standard \*nix makefiles or Xcode. In order to generate and build from makefiles, in the root `bond` directory run: - mkdir build - cd build - cmake .. - make - sudo make install +```bash +mkdir build +cd build +cmake .. +make +sudo make install +``` Alternatively, you can generate Xcode projects by passing the `-G Xcode` option to cmake: - cmake -G Xcode .. +```bash +cmake -G Xcode .. +``` You can build and run unit tests by building the `check` target in Xcode or by running make in the build directory: - make --jobs 8 check +```bash +make --jobs 8 check +``` Note that if you are using Homebrew's Python, you'll need to build boost-python from source: - brew install --build-from-source boost-python +```bash +brew install --build-from-source boost-python +``` and tell cmake the location of Homebrew's libpython by setting the `PYTHON_LIBRARY` variable, e.g.: - cmake .. \ - -DPYTHON_LIBRARY=/usr/local/Cellar/python/2.7.9/Frameworks/Python.framework/Versions/2.7/lib/libpython2.7.dylib +```bash +cmake .. \ + -DPYTHON_LIBRARY=/usr/local/Cellar/python/2.7.9/Frameworks/Python.framework/Versions/2.7/lib/libpython2.7.dylib +``` ### Windows @@ -158,11 +184,15 @@ Install the following tools: If you are building on a network behind a proxy, set the environment variable `HTTP_PROXY`, e.g.: - set HTTP_PROXY=http://your-proxy-name:80 +```bash +set HTTP_PROXY=http://your-proxy-name:80 +``` Update the cabal package database: - cabal update +```bash +cabal update +``` Now you are ready to build the C# version of Bond. Open the solution file `cs\cs.sln` in Visual Studio and build as usual. The C# unit tests can @@ -177,8 +207,10 @@ You may need to set the environment variables `BOOST_ROOT` and `BOOST_LIBRARYDIR to specify where Boost and its pre-built libraries for your environment (MSVC 12 or MSVC 14) can be found, e.g.: - set BOOST_ROOT=D:\boost_1_57_0 - set BOOST_LIBRARYDIR=D:\boost_1_57_0\lib64-msvc-14.0 +```bash +set BOOST_ROOT=D:\boost_1_57_0 +set BOOST_LIBRARYDIR=D:\boost_1_57_0\lib64-msvc-14.0 +``` The core Bond library and most examples only require Boost headers. The pre-built libraries are only needed for unit tests and Python support. If Boost @@ -188,29 +220,37 @@ not be built. In order to generate a solution to build the C++ and Python versions with Visual Studio 2015 run the following commands from the root `bond` directory: - mkdir build - cd build - set PreferredToolArchitecture=x64 - cmake -G "Visual Studio 14 2015 Win64" .. +```bash +mkdir build +cd build +set PreferredToolArchitecture=x64 +cmake -G "Visual Studio 14 2015 Win64" .. +``` Setting `PreferredToolArchitecture=x64` selects the 64-bit toolchain which dramatically improves build speed. (The Bond unit tests are too big to build with 32-bit tools.) This variable works for Visual Studio 2013 or 2015. For Visual Studio 2012 set the following environment variable instead: - set _IsNativeEnvironment=true +```bash +set _IsNativeEnvironment=true +``` Instead of `cmake` you can also use `cmake-gui` and specify configuration settings in the UI. This configuration step has to be performed only once. From then on you can use the generated solution `build\bond.sln` from Visual Studio or build from command line using `cmake`: - cmake --build . --target - cmake --build . --target INSTALL +```bash +cmake --build . --target +cmake --build . --target INSTALL +``` In order to build and execute the unit tests and examples run: - cmake --build . --target check -- /maxcpucount:8 +```bash +cmake --build . --target check -- /maxcpucount:8 +``` ## Contributing diff --git a/doc/.pandoc/templates/default.html b/doc/.pandoc/templates/default.html index 2ec7dff0..9f98ac26 100644 --- a/doc/.pandoc/templates/default.html +++ b/doc/.pandoc/templates/default.html @@ -16,8 +16,8 @@ $if(highlighting-css)$ $highlighting-css$ $endif$ body { - line-height: 1.5; - font-family: Helvetica, Arial, sans-serif; + line-height: 1.5; + font-family: Helvetica, Arial, sans-serif; color: #333333; font-size: 1em; } @@ -33,7 +33,7 @@ $endif$ padding: 25px; overflow: auto; } - code > span.kw { color: #204a87; font-weight: normal; } /* Keyword */ + code > span.kw { color: #204a87; font-weight: normal; } /* Keyword */ code > span.co { color: #4E9A06; font-style: normal; } code > span.st { color: #8A0303; font-style: normal; } code > span.cf { color: #204a87; font-weight: normal; } /* ControlFlow */ @@ -56,19 +56,19 @@ $endif$ max-height: 620px; } - table.sourceCode { + table.sourceCode { line-height: 120%; - } + } #toc { - width: 300px; + width: 300px; position:fixed; overflow: auto; height: 95%; } #main { - margin-left: 320px; + margin-left: 320px; margin-rigth: auto; max-width: 800px; } @@ -90,7 +90,7 @@ $endif$ margin-right: auto; } #toc { - left: -300px; + left: -300px; } } @@ -120,14 +120,15 @@ $endfor$ $for(include-before)$ $include-before$ $endfor$ -$if(toc)$
+

The Bond logo: a stylized glue gun

+$if(toc)$ $toc$ -
$endif$ +
$if(title)$ -
+

$title$

$for(author)$

$author$

@@ -138,7 +139,7 @@ $endif$
$endif$ $body$ -
+
$for(include-after)$ $include-after$ $endfor$ diff --git a/doc/.pandoc/templates/index.html b/doc/.pandoc/templates/index.html deleted file mode 100644 index 2a832ba8..00000000 --- a/doc/.pandoc/templates/index.html +++ /dev/null @@ -1,154 +0,0 @@ - - - - - - -$for(author-meta)$ - -$endfor$ -$if(date-meta)$ - -$endif$ - $if(title-prefix)$$title-prefix$ - $endif$$if(pagetitle)$$pagetitle$$endif$ - -$for(css)$ - -$endfor$ -$if(math)$ - $math$ -$endif$ -$for(header-includes)$ - $header-includes$ -$endfor$ - - - -