~loggerhead-team/loggerhead/trunk-rich : contents of docs/index.rst at revision 449

~loggerhead-team/loggerhead/trunk-rich : (revision 449)

401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	1	Loggerhead: A web viewer for ``bzr`` branches
401.2.1 by Tres Seaver Add Sphinx-based documentation.	2	==============================================
401.2.1 by Tres Seaver Add Sphinx-based documentation.	3
401.2.11 by Ian Clatworthy Minor tweaks to Tres' content	4	Loggerhead is a web viewer for projects in Bazaar. It can be used to navigate
401.2.1 by Tres Seaver Add Sphinx-based documentation.	5	a branch history, annotate files, view patches, perform searches, etc.
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	6	Loggerhead is heavily based on `bazaar-webserve
401.2.4 by Tres Seaver Move cross-ref of bazaar-webserve and hgweb to intro graph; remove dead modindex and search.	7	<https://launchpad.net/bzr-webserve>`_, which was, in turn, loosely
	8	based on `hgweb <http://mercurial.selenic.com/wiki/HgWebDirStepByStep>`_.
	9
401.2.1 by Tres Seaver Add Sphinx-based documentation.	10
	11	Getting Started
	12	---------------
	13
401.2.2 by Tres Seaver ReST fixups, better cross-references.	14	Loggerhead depends on the following Python libraries.:
	15
	16	- SimpleTAL for templating.
	17
	18	- simplejson for producing JSON data.
	19
401.2.8 by Tres Seaver Consistent punctuation.	20	- Paste for the server. (You need version 1.2 or newer of Paste).
	21
	22	- Paste Deploy (optional, needed when proxying through Apache).
	23
	24	- flup (optional, needed to use FastCGI, SCGI or AJP).
401.2.2 by Tres Seaver ReST fixups, better cross-references.	25
	26
	27	Installing Dependencies Using Ubuntu Packages
	28	#############################################
	29
	30	.. code-block:: sh
	31
	32	$ sudo apt-get install python-simpletal
	33	$ sudo apt-get install python-simplejson
	34	$ sudo apt-get install python-paste
	35	$ sudo apt-get install python-pastedeploy
	36	$ sudo apt-get install python-flup
	37
	38	Installing Dependencies Using :command:`easy_install`
	39	#####################################################
	40
	41	.. code-block:: sh
	42
	43	$ easy_install \
	44	-f http://www.owlfish.com/software/simpleTAL/py2compatible/download.html \
	45	SimpleTAL
	46	$ easy_install simplejson
	47	$ easy_install Paste
	48	$ easy_install PasteDeploy
	49	$ easy_install flup
	50
	51
	52	Running the Standalone Loggerhead Server
	53	----------------------------------------
	54
	55	After installing all the dependencies, you should be able to run
	56	:command:`serve-branches` with the branch you want to serve on the
	57	command line:
401.2.1 by Tres Seaver Add Sphinx-based documentation.	58
	59	.. code-block:: sh
	60
	61	./serve-branches ~/path/to/branch
	62
401.2.2 by Tres Seaver ReST fixups, better cross-references.	63	By default, the script listens on port 8080, so head to
	64	http://localhost:8080/ in your browser to see the branch.
	65
	66	You can also pass a directory that contains branches to the script,
	67	and it will serve a very simple directory listing at other pages.
401.2.1 by Tres Seaver Add Sphinx-based documentation.	68
	69	You may update the Bazaar branches being viewed at any time.
	70	Loggerhead will notice and refresh, and Bazaar uses its own branch
	71	locking to prevent corruption.
	72
401.2.2 by Tres Seaver ReST fixups, better cross-references.	73	See :doc:`serve-branches` for all command line options.
	74
	75	Running Loggerhead as a Daemon
	76	------------------------------
	77
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	78	To run Loggerhead as a linux daemon:
401.2.1 by Tres Seaver Add Sphinx-based documentation.	79
401.2.2 by Tres Seaver ReST fixups, better cross-references.	80	1) Copy the ``loggerheadd`` scipt to ``/etc/init.d``
	81
	82	.. code-block:: sh
	83
	84	$ sudo cp ./loggerheadd /etc/init.d
401.2.1 by Tres Seaver Add Sphinx-based documentation.	85
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	86	2) Edit the file to configure where your Loggerhead is installed, and which
401.2.1 by Tres Seaver Add Sphinx-based documentation.	87	serve-branches options you would like.
401.2.1 by Tres Seaver Add Sphinx-based documentation.	88
401.2.2 by Tres Seaver ReST fixups, better cross-references.	89	.. code-block:: sh
	90
	91	$ sudo vim /etc/init.d/loggerheadd
	92
401.2.1 by Tres Seaver Add Sphinx-based documentation.	93	3) Register the service
401.2.2 by Tres Seaver ReST fixups, better cross-references.	94
	95	.. code-block:: sh
	96
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	97	# on upstart based systems like Ubuntu run:
401.2.2 by Tres Seaver ReST fixups, better cross-references.	98	$ sudo update-rc.d loggerheadd defaults
	99
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	100	# on Sysvinit based systems like Centos or SuSE run:
401.2.2 by Tres Seaver ReST fixups, better cross-references.	101	$ sudo chkconfig --add loggerheadd
	102
	103
	104	Using Loggerhead as a Bazaar Plugin
	105	------------------------------------
401.2.1 by Tres Seaver Add Sphinx-based documentation.	106
	107	This branch contains experimental support for using Loggerhead as a Bazaar
	108	plugin. To use it, place the top-level Loggerhead directory (the one
401.2.11 by Ian Clatworthy Minor tweaks to Tres' content	109	containing COPYING.txt) at ``~/.bazaar/plugins/loggerhead``. E.g.:
401.2.3 by Tres Seaver Explain plugin usage, link bazaar-webserve and hgweb.	110
	111	.. code-block:: sh
	112
	113	$ bzr branch lp:loggerhead ~/.bazaar/plugins/loggerhead
	114	$ cd ~/myproject
	115	$ bzr serve --http
401.2.1 by Tres Seaver Add Sphinx-based documentation.	116
	117
	118	Using a Config File
	119	-------------------
	120
	121	To hide branches from being displayed, add to ``~/.bazaar/locations.conf``,
	122	under the branch's section:
	123
	124	.. code-block:: ini
	125
	126	[/path/to/branch]
	127	http_serve = False
	128
	129	More configuration options to come soon.
	130
	131
401.2.6 by Tres Seaver Better section title.	132	Serving Loggerhead behind Apache
401.2.6 by Tres Seaver Better section title.	133	--------------------------------
401.2.1 by Tres Seaver Add Sphinx-based documentation.	134
	135	If you want to view Bazaar branches from your existing Apache
	136	installation, you'll need to configure Apache to proxy certain
401.2.11 by Ian Clatworthy Minor tweaks to Tres' content	137	requests to Loggerhead. Adding lines like this to your Apache
401.2.1 by Tres Seaver Add Sphinx-based documentation.	138	configuration is one way to do this:
	139
	140	.. code-block:: apache
	141
	142	<Location "/branches/">
	143	ProxyPass http://127.0.0.1:8080/branches/
	144	ProxyPassReverse http://127.0.0.1:8080/branches/
	145	</Location>
	146
	147	If Paste Deploy is installed, the :command:`serve-branches` script can be
	148	run behind a proxy at the root of a site, but if you're running it at
401.2.11 by Ian Clatworthy Minor tweaks to Tres' content	149	some path into the site, you'll need to specify it using
401.2.1 by Tres Seaver Add Sphinx-based documentation.	150	``--prefix=/some_path``.
	151
	152
	153	Search
	154	------
	155
	156	Search is currently supported by using the bzr-search plugin (available
401.2.2 by Tres Seaver ReST fixups, better cross-references.	157	at: https://launchpad.net/bzr-search ).
	158
401.2.1 by Tres Seaver Add Sphinx-based documentation.	159	You need to have the plugin installed and each branch indexed to allow
	160	searching on branches.
	161
401.2.5 by Tres Seaver Better section title.	162	Command-Line Reference
401.2.5 by Tres Seaver Better section title.	163	----------------------
401.2.2 by Tres Seaver ReST fixups, better cross-references.	164
	165	.. toctree::
	166	:maxdepth: 2
	167
	168	serve-branches
	169
401.2.1 by Tres Seaver Add Sphinx-based documentation.	170
	171	Support
	172	-------
	173
401.2.3 by Tres Seaver Explain plugin usage, link bazaar-webserve and hgweb.	174	Discussion should take place on the bazaar-dev mailing list at
	175	mailto:bazaar@lists.canonical.com. You can join the list at
401.2.1 by Tres Seaver Add Sphinx-based documentation.	176	<https://lists.ubuntu.com/mailman/listinfo/bazaar>. You don't need to
	177	subscribe to post, but your first post will be held briefly for manual
	178	moderation.
	179
401.2.11 by Ian Clatworthy Minor tweaks to Tres' content	180	Bugs, support questions and merge proposals are tracked on Launchpad, e.g:
401.2.1 by Tres Seaver Add Sphinx-based documentation.	181
	182	https://bugs.launchpad.net/loggerhead
	183
	184
	185	Hacking
	186	-------
	187
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	188	To run Loggerhead tests, you will need to install the package ``python-nose``,
	189	and run its :command:`nosetests` script in the Loggerhead directory:
401.2.1 by Tres Seaver Add Sphinx-based documentation.	190
	191	.. code-block:: sh
	192
	193	nosetests
	194
401.2.2 by Tres Seaver ReST fixups, better cross-references.	195
401.2.1 by Tres Seaver Add Sphinx-based documentation.	196	License
	197	-------
	198
	199	GNU GPLv2 or later.
	200
	201	See Also
	202	--------
	203
	204	https://launchpad.net/loggerhead
	205
401.2.4 by Tres Seaver Move cross-ref of bazaar-webserve and hgweb to intro graph; remove dead modindex and search.	206	Index
	207	=====
	208
	209	- :ref:`genindex`