Add Sphinx-related build changes into READMEs
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/86be5a68 Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/86be5a68 Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/86be5a68 Branch: refs/heads/1536-feature_add-docs Commit: 86be5a6897ec71d1c556668b71ee9b3e4fcc618e Parents: 392723c Author: Noah Slater <[email protected]> Authored: Mon Dec 3 10:04:54 2012 +0100 Committer: Dave Cottlehuber <[email protected]> Committed: Mon Dec 3 14:17:07 2012 +0100 ---------------------------------------------------------------------- AUTHORS | 1 - BUGS | 6 ++- DEVELOPERS | 114 ++++++++++++++++++++++++++++++++++++++++++------- INSTALL.Unix | 55 +++++++++++++++++------- INSTALL.Windows | 36 ++++++++++----- LICENSE | 115 ++++++++++++++++++++++++++++++++++++++++++++++---- NOTICE | 28 ++++++------ README | 4 ++ 8 files changed, 289 insertions(+), 70 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/AUTHORS ---------------------------------------------------------------------- diff --git a/AUTHORS b/AUTHORS index e55c0b0..49b5ef1 100644 --- a/AUTHORS +++ b/AUTHORS @@ -21,5 +21,4 @@ documentation or developing software. Some of these people are: * Dave Cottlehuber <[email protected]> * Jason Smith <[email protected]> - For a list of other credits see the `THANKS` file. http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/BUGS ---------------------------------------------------------------------- diff --git a/BUGS b/BUGS index 8cd1d16..1bdc478 100644 --- a/BUGS +++ b/BUGS @@ -1,6 +1,8 @@ Apache CouchDB BUGS =================== -Please see the [documentation][1] on how to report bugs with Apache CouchDB. +Visit our issue tracker: -[1] http://couchdb.apache.org/community/issues.html + https://issues.apache.org/jira/browse/CouchDB + +You can use this to report bugs, request features, or suggest enhancements. http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/DEVELOPERS ---------------------------------------------------------------------- diff --git a/DEVELOPERS b/DEVELOPERS index 84976d7..f61b77b 100644 --- a/DEVELOPERS +++ b/DEVELOPERS @@ -10,30 +10,95 @@ Dependencies You will need the following installed: - * GNU Automake (>=1.6.3) (http://www.gnu.org/software/automake/) - * GNU Autoconf (>=2.59) (http://www.gnu.org/software/autoconf/) * GNU Libtool (http://www.gnu.org/software/libtool/) + * GNU Automake (>=1.6.3) (http://www.gnu.org/software/automake/) + * GNU Autoconf (>=2.68) (http://www.gnu.org/software/autoconf/) + * GNU Autoconf Archive (http://www.gnu.org/software/autoconf-archive/) + * pkg-config (http://www.freedesktop.org/wiki/Software/pkg-config) + +You may also need: + + * Sphinx (http://sphinx.pocoo.org/) + * LaTex (http://www.latex-project.org/) + * GNU Texinfo (http://www.gnu.org/software/texinfo/) * GNU help2man (http://www.gnu.org/software/help2man/) -The `help2man` tool is optional, but will generate `man` pages for you. +These optional dependencies are required for building the documentation. + +You will need these optional dependencies installed if: + + * You are preparing a distribution archive + +However, you do not need them if: + + * You are building from a distribution archive, or + * You don't care about building the documentation Debian-based (inc. Ubuntu) Systems ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can install the dependencies by running: +You can install the required dependencies by running: + + sudo apt-get install libtool + sudo apt-get install automake + sudo apt-get install autoconf + sudo apt-get install autoconf-archive + sudo apt-get install pkg-config - apt-get install automake autoconf libtool help2man +Optional dependencies: + + sudo apt-get install help2man + sudo apt-get install python-sphinx + sudo apt-get install texlive-latex-base + sudo apt-get install texlive-latex-recommended + sudo apt-get install texlive-latex-extra + sudo apt-get install texlive-fonts-recommended + sudo apt-get install texinfo Be sure to update the version numbers to match your system's available packages. Mac OS X ~~~~~~~~ -You can install the dependencies by running: +Install Homebrew, if you do not have it already: + + https://github.com/mxcl/homebrew + +You can install the required dependencies by running: + + brew install libtool + brew install automake + brew install autoconf + brew install autoconf-archive + brew install pkg-config + +Unless you want to install the optional dependencies, skip to the next section. - port install automake autoconf libtool help2man +Install what else we can with Homebrew: -You will need MacPorts installed to use the `port` command. + brew install help2man + +If you don't already have pip installed, install it: + + sudo easy_install pip + +Now, install the required Python packages: + + sudo pip install sphinx + sudo pip install docutils + sudo pip install pygments + +Download MaxTeX from here: + + http://www.tug.org/mactex/ + +Follow the instructions to get a working LaTeX install on your system. + +Windows +~~~~~~~ + + Follow the instructions in INSTALL.Windows and build all components + from source, using the same Visual C++ compiler and runtime. Bootstrapping ------------- @@ -44,6 +109,29 @@ Bootstrap the pristine source by running: You must repeat this step every time you update your source checkout. +Configuring +----------- + +Configure the source by running: + + ./configure + +Note that this will not fail when the optional dependencies are missing. + +To ensure the optional dependencies are installed, run: + + ./configure --enable-strictness + +If you don't care about docs and want to skip the whole thing, run: + + ./configure --disable-docs + +If you're working on the build system itself, you can run: + + ./configure --disable-tests + +This skips the tests allowing quicker `make' cycles. + Testing ------- @@ -60,17 +148,13 @@ Please report any problems to the developer's mailing list. Releasing --------- -The release procedure is documented in the project wiki: +The release procedure is documented here: https://wiki.apache.org/couchdb/Release_procedure Unix-like Systems ~~~~~~~~~~~~~~~~~ -Configure the source by running: - - ./configure - Prepare the release artefacts by running: make distcheck @@ -84,10 +168,6 @@ The release artefacts can be found in the root source directory. Microsoft Windows ~~~~~~~~~~~~~~~~~ -Configure the source by running: - - ./configure - Prepare the release artefacts by running: make dist http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/INSTALL.Unix ---------------------------------------------------------------------- diff --git a/INSTALL.Unix b/INSTALL.Unix index baf9d06..3e9dce5 100644 --- a/INSTALL.Unix +++ b/INSTALL.Unix @@ -3,6 +3,16 @@ Apache CouchDB README.Unix A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu. +Community installation guides are available on the wiki: + + http://wiki.apache.org/couchdb/Installation + +This document is the canonical source of installation information. However, many +systems have gotchas that you need to be aware of. In addition, dependencies +frequently change as distributions update their archives. If you're running into +trouble, be sure to check out the wiki. If you have any tips to share, please +also update the wiki so that others can benefit from your experience. + Troubleshooting --------------- @@ -33,32 +43,42 @@ You should have the following installed: * GNU Compiler Collection (http://gcc.gnu.org/) * libcurl (http://curl.haxx.se/libcurl/) * help2man (http://www.gnu.org/s/help2man/) + * Python (>= 2.7) for docs (http://python.org/) + * Python Sphinx (>=1.1.3) (http://pypi.python.org/pypi/Sphinx) -It is recommended that you install Erlang OTP R12B-5 or above where possible. -You will only need libcurl if you plan to run the JavaScript test suite. And +It is recommended that you install Erlang OTP R13B04 or above where possible. +You will only need libcurl if you plan to run the JavaScript test suite. help2man is only need if you plan on installing the CouchDB man pages. - -Ubuntu -~~~~~~ - -For up to date instructions, please see: - - http://wiki.apache.org/couchdb/Installing_on_Ubuntu - -Unfortunately, it seems that installing dependancies on Ubuntu is troublesome. +Python and Sphinx are only required for building the online documentation. Debian-based Systems ~~~~~~~~~~~~~~~~~~~~ -You can install the build tools by running: +You can install the dependencies by running: sudo apt-get install build-essential + sudo apt-get install erlang-base-hipe + sudo apt-get install erlang-dev + sudo apt-get install erlang-manpages + sudo apt-get install erlang-eunit + sudo apt-get install erlang-nox + sudo apt-get install libicu-dev + sudo apt-get install libmozjs-dev + sudo apt-get install libcurl4-openssl-dev + +There are lots of Erlang packages. If there is a problem with your install, try +a different mix. There is more information on the wiki. Additionally, you might +want to install some of the optional Erlang tools which may also be useful. -You can install the other dependencies by running: +Be sure to update the version numbers to match your system's available packages. + +For up to date instructions, please see: - sudo apt-get install erlang libicu-dev libmozjs-dev libcurl4-openssl-dev + http://wiki.apache.org/couchdb/Installing_on_Debian -Be sure to update the version numbers to match your system's available packages. + http://wiki.apache.org/couchdb/Installing_on_Ubuntu + +Unfortunately, it seems that installing dependencies on Ubuntu is troublesome. Mac OS X ~~~~~~~~ @@ -69,7 +89,10 @@ You can install the build tools by running: You can install the other dependencies by running: - brew install erlang icu4c spidermonkey curl + brew install erlang + brew install icu4c + brew install spidermonkey + brew install curl You may want to link ICU so that CouchDB can find the header files automatically: http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/INSTALL.Windows ---------------------------------------------------------------------- diff --git a/INSTALL.Windows b/INSTALL.Windows index b75b80a..89ab231 100644 --- a/INSTALL.Windows +++ b/INSTALL.Windows @@ -14,6 +14,10 @@ There is a wiki for general documentation: http://wiki.apache.org/couchdb/ +And some Windows-specific tips: + + http://wiki.apache.org/couchdb/Quirks_on_Windows + There are collection of friendly mailing lists: http://couchdb.apache.org/community/lists.html @@ -25,28 +29,36 @@ Dependencies You will need the following installed: - * Erlang OTP (=14B01) (http://erlang.org/) - * ICU (=4.4.*) (http://icu.sourceforge.net/) - * OpenSSL (http://www.openssl.org/) - * Mozilla SpiderMonkey (1.7) (http://www.mozilla.org/js/spidermonkey/) - * libcurl (http://curl.haxx.se/libcurl/) - * Cygwin (http://www.cygwin.com/) - * Visual Studio 2008 (http://msdn.microsoft.com/en-gb/vstudio/default.aspx) + * Erlang OTP (>=14B01) (http://erlang.org/) + * ICU (>=4.*) (http://icu.sourceforge.net/) + * OpenSSL (>=0.9.8r) (http://www.openssl.org/) + * Mozilla SpiderMonkey (=1.8.5) (http://www.mozilla.org/js/spidermonkey/) + * libcurl (http://curl.haxx.se/libcurl/) + * Cygwin (http://www.cygwin.com/) + * Microsoft SDK 7.0 or 7.1 (http://www.microsoft.com/en-us/download/details.aspx?id=8279) + * Python (>= 2.7) for docs (http://python.org/) + * Python Sphinx (>=1.1.3) (http://pypi.python.org/pypi/Sphinx) General Notes ------------- + * When installing Cygwin, be sure to select all the `development` tools. + * When installing Erlang, you must build it from source. - The CouchDB build requires a number of the Erlang build scripts. + * The CouchDB build requires a number of the Erlang build scripts. - * When installing ICU, select the binaries built with Visual Studio 2008. + * All dependent libraries should be built with the same version of + microsoft SDK. - * When installing Cygwin, be sure to select all the `development` tools. + * Do not try to link against libraries built with, or included in, + Cygwin or MingW. They are not compatible with the Erlang/OTP or CouchDB + build scripts. - * When installing libcurl, be sure to install by hand. + * ICU version 4.6 and later will build cleanly using MSBuild. - The Cygwin binaries are incompatible and will not work with Erlang. + * Python and Sphinx are only required for building the online documentation. + Use cygwin-provided Python and install Sphinx via easy_install or pip. Setting Up Cygwin ----------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/LICENSE ---------------------------------------------------------------------- diff --git a/LICENSE b/LICENSE index be511b1..be2404d 100644 --- a/LICENSE +++ b/LICENSE @@ -201,20 +201,120 @@ See the License for the specific language governing permissions and limitations under the License. - Apache CouchDB Subcomponents The Apache CouchDB project includes a number of subcomponents with separate copyright notices and license terms. Your use of the code for the these subcomponents is subject to the terms and conditions of the following licenses. -For the m4/ac_check_icu.m4 component: +For the share/doc/build/html/_static components: + + Copyright (c) 2007-2011 by the Sphinx team (see AUTHORS file). + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +For the share/doc/build/html/_static/jquery.js component: + + Copyright 2010, John Resig + + Copyright 2010, The Dojo Foundation + + Copyright 2012 jQuery Foundation and other contributors + http://jquery.com/ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +For the share/doc/build/html/_static/underscore.js component: + + Copyright (c) 2009-2012 Jeremy Ashkenas, DocumentCloud - Copyright (c) 2005 Akos Maroy <[email protected]> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT + HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE. + +For the share/doc/static/rtd.css components: + + Copyright (c) 2007-2011 by the Sphinx team (see AUTHORS file). + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. - Copying and distribution of this file, with or without modification, are - permitted in any medium without royalty provided the copyright notice - and this notice are preserved. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. For the share/www/script/jquery.js component: @@ -239,8 +339,7 @@ For the share/www/script/jquery.js component: OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -For the share/www/script/jquery-ui-1.8.11.custom.min.js and - share/www/style/jquery-ui-1.8.11.custom.css components: +For the share/www/script/jquery-ui-* components: Copyright (c) 2011 Paul Bakaus, http://jqueryui.com/ http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/NOTICE ---------------------------------------------------------------------- diff --git a/NOTICE b/NOTICE index ef3ff9e..e627b92 100644 --- a/NOTICE +++ b/NOTICE @@ -6,18 +6,6 @@ The Apache Software Foundation (http://www.apache.org/). This product also includes the following third-party components: - * ac_check_icu.m4 (http://autoconf-archive.cryp.to/ac_check_icu.html) - - Copyright 2008, Akos Maroy <[email protected]> - - * ac_check_curl.m4 (http://autoconf-archive.cryp.to/ac_check_curl.html) - - Copyright 2008, Akos Maroy <[email protected]> - - * pkg.m4 (http://http://pkg-config.freedesktop.org/wiki/) - - Copyright 2004, Scott James Remnant <[email protected]> - * jQuery (http://jquery.com/) Copyright 2011, John Resig @@ -28,7 +16,7 @@ This product also includes the following third-party components: * json2.js (http://www.json.org/) - In the public domain + Public domain * MochiWeb (http://code.google.com/p/mochiweb/) @@ -64,7 +52,7 @@ This product also includes the following third-party components: * snappy (http://code.google.com/p/snappy/) - Copyright 2005 and onwards Google Inc. + Copyright 2005, Google Inc. * snappy-erlang-nif (https://github.com/fdmanana/snappy-erlang-nif) @@ -73,3 +61,15 @@ This product also includes the following third-party components: * CoffeeScript (http://coffeescript.org/) Copyright 2011, Jeremy Ashkenas + + * Sphinx (http://sphinx-doc.org/) + + Copyright 2011, the Sphinx team + + * Sizzle (http://sizzlejs.com/) + + Copyright 2010, The Dojo Foundation + + * Underscore.js 1.4.2 (http://underscorejs.org) + + Copyright 2012, Jeremy Ashkenas http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/README ---------------------------------------------------------------------- diff --git a/README b/README index 0d125fb..33b854d 100644 --- a/README +++ b/README @@ -34,6 +34,10 @@ If you're getting a cryptic error message, see: For general help, see: http://couchdb.apache.org/#mailing-list + +We also have an IRC channel: + + http://webchat.freenode.net/?channels=couchdb The mailing lists provide a wealth of support and knowledge for you to tap into. Feel free to drop by with your questions or discussion. See the official CouchDB
