PageRenderTime 46ms CodeModel.GetById 16ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/build/index.html

https://bitbucket.org/nautilebleu/django_hg/
HTML | 210 lines | 197 code | 13 blank | 0 comment | 0 complexity | a58d88f35029e78f2ffde0ee9767563f MD5 | raw file
Possible License(s): BSD-3-Clause 
    

  1. <?xml version="1.0" encoding="UTF-8"?>
    2. 

  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    3. 

  3. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    4. 

  4. <head>
    5. 

  5.     <title>Documentation > Index</title>
    6. 

  6.     <link rel="stylesheet" href="css/screen.css" />
    7. 

  7.     <link rel="stylesheet" href="css/codehilite.css" />
    8. 

  8.     <script src="js/jquery-1.3.2.min.js" type="text/javascript"></script>
    9. 

  9.     <script src="js/referencrz.js" type="text/javascript"></script>
    10. 

  10. </head>
    11. 

  11. <body id="body">
    12. 

  12.     <div id="body-header" class="admin">
    13. 

  13.       <h1><a href="index.html">Documentation</a></h1>
    14. 

  14.     </div>
    15. 

  15.     <div id="body-content">
    16. 

  16.       <div id="sf_admin_container">
    17. 

  17.         <div class="toc">
    18. 

  18. <ul>
    19. 

  19. <li><a href="#using-django_hg">Using django_hg</a><ul>
    20. 

  20. <li><a href="#why-use-django_hg">Why use django_hg ?</a></li>
    21. 

  21. <li><a href="#install">Install</a></li>
    22. 

  22. <li><a href="#usage">Usage</a><ul>
    23. 

  23. <li><a href="#administration">Administration</a></li>
    24. 

  24. <li><a href="#public">Public</a><ul>
    25. 

  25. <li><a href="#list">List</a></li>
    26. 

  26. <li><a href="#repository">Repository</a></li>
    27. 

  27. <li><a href="#file">File</a></li>
    28. 

  28. </ul>
    29. 

  29. </li>
    30. 

  30. <li><a href="#hg-commands-clone-push-and-pull">Hg commands (clone, push and pull)</a></li>
    31. 

  31. </ul>
    32. 

  32. </li>
    33. 

  33. <li><a href="#templating">Templating</a></li>
    34. 

  34. <li><a href="#deployment">Deployment</a></li>
    35. 

  35. <li><a href="#to-dos">To-dos</a></li>
    36. 

  36. <li><a href="#requirements">Requirements</a></li>
    37. 

  37. </ul>
    38. 

  38. </li>
    39. 

  39. </ul>
    40. 

  40. </div>
    41. 

  41. <h1 id="using-django_hg">Using django_hg</h1>
    42. 

  42. <h2 id="why-use-django_hg">Why use django_hg ?</h2>
    43. 

  43. <p><a href="http://bitbucket.org/nautilebleu/django_hg/">django_hg [en]</a> aims to allow browsing a <a href="http://selenic.com/mercurial/">Mercurial [en]</a> repository into a <a href="http://djangoproject.com/">django [en]</a> project.</p>
    44. 

  44. <p>Even if Mercurial has a built-in webserver, I think there's room for a
    45. 

  45. django-integrated solution:</p>
    46. 

  46. <ul>
    47. 

  47. <li>better integration with other components of the website, especially for the
    48. 

  48.   graphics. django templates are much easy to understand than Mercurial
    49. 

  49.   templates.</li>
    50. 

  50. <li>allow to browse more than one repository, without installing <code>hgwebdir.cgi</code>.</li>
    51. 

  51. <li>django authentication</li>
    52. 

  52. <li>links with a django-powered bug tracker such as
    53. 

  53.   <a href="http://opensource.washingtontimes.com/projects/django-projectmgr/">django-projectmgr [en]</a> (to-do)</li>
    54. 

  54. </ul>
    55. 

  55. <p>Currently, this project is in his early stages of development and not all
    56. 

  56. features of the Mercurial integrated webserver are implemented. If you need an
    57. 

  57. out-of-box ready solution, you should currently use Mercurial built-in
    58. 

  58. webserver. You may want to read <a href="http://hgbook.red-bean.com/">Mercurial: The Definitive Guide [en]</a>,
    59. 

  59. and especially the <a href="http://hgbook.red-bean.com/read/collaborating-with-other-people.html">Chapter 6 [en]</a>, for more informations about
    60. 

  60. configuring Mercurial webserver.</p>
    61. 

  61. <h2 id="install">Install</h2>
    62. 

  62. <p>django_hg follows <a href="http://ericholscher.com/projects/django-conventions/app/">django reusable apps conventions [en]</a>
    63. 

  63. and install is quite easy:</p>
    64. 

  64. <p>Clone <code>django_hg</code> from <a href="http://bitbucket.org/">bitbucket [en]</a> somewhere in your
    65. 

  65. <code>PYTHONPATH</code>:</p>
    66. 

  66. <div class="codehilite"><pre><span class="nv">$ </span>hg clone https://bitbucket.org/nautilebleu/django_hg/ django_hg
    67. 

  67. </pre></div>
    68. 

  68. 

  69. 

  70. <p>Configure your <code>settings.py</code>:</p>
    71. 

  71. <div class="codehilite"><pre><span class="c"># /PROJECT/APP/settings.py</span>
    72. 

  72. <span class="c"># django_hg settings</span>
    73. 

  73. <span class="n">DJANGO_HG_REPOSITORIES_DIR</span> <span class="o">=</span> <span class="p">{</span>
    74. 

  74.   <span class="s">&quot;public&quot;</span><span class="p">:</span> <span class="s">&quot;/Users/goulwen/Repositories/public/&quot;</span><span class="p">,</span>
    75. 

  75.   <span class="s">&quot;private&quot;</span><span class="p">:</span> <span class="s">&quot;/Users/goulwen/Repositories/private/&quot;</span>
    76. 

  76. <span class="p">}</span>
    77. 

  77. <span class="n">DJANGO_HG_PAGER_ITEMS</span> <span class="o">=</span> <span class="mf">30</span>
    78. 

  78. <span class="c"># one of pygment styles : autumn, borland, bw, colorful, default, emacs,</span>
    79. 

  79. <span class="c"># friendly, fruity, manni, murphy, native, pastie, perldoc, tango, trac, vim,</span>
    80. 

  80. <span class="c"># vs</span>
    81. 

  81. <span class="n">DJANGO_HG_PYGMENT_STYLE</span> <span class="o">=</span> <span class="s">&#39;tango&#39;</span>
    82. 

  82. <span class="c"># The maximum of search results returned when performing a search in a repository</span>
    83. 

  83. <span class="n">DJANGO_HG_MAX_SEARCH_RESULTS</span> <span class="o">=</span> <span class="mf">100</span>
    84. 

  84. 

  85. <span class="c"># templates dir</span>
    86. 

  86. <span class="n">TEMPLATE_DIRS</span> <span class="o">=</span> <span class="p">(</span>
    87. 

  87.     <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="n">__file__</span><span class="p">),</span> <span class="s">&#39;templates&#39;</span><span class="p">),</span>
    88. 

  88.     <span class="s">&#39;/Users/goulwen/Dev/Python/django_hg/templates&#39;</span><span class="p">,</span>
    89. 

  89. <span class="p">)</span>
    90. 

  90. 

  91. <span class="c"># if not already done, add the DJANGO.CORE.CONTEXT_PROCESSORS.REQUEST and</span>
    92. 

  92. <span class="c"># the DJANGO.CORE.CONTEXT_PROCESSORS.MEDIA to settings</span>
    93. 

  93. <span class="n">TEMPLATE_CONTEXT_PROCESSORS</span> <span class="o">=</span> <span class="p">(</span>
    94. 

  94.     <span class="s">&#39;django.core.context_processors.request&#39;</span><span class="p">,</span>
    95. 

  95.     <span class="s">&#39;django.core.context_processors.media&#39;</span><span class="p">,</span>
    96. 

  96. <span class="p">)</span>
    97. 

  97. 

  98. <span class="c"># add to installed apps</span>
    99. 

  99. <span class="n">INSTALLED_APPS</span> <span class="o">=</span> <span class="p">(</span>
    100. 

  100.     <span class="c"># …</span>
    101. 

  101.     <span class="s">&#39;django_hg&#39;</span><span class="p">,</span>
    102. 

  102. <span class="p">)</span>
    103. 

  103. </pre></div>
    104. 

  104. 

  105. 

  106. <p>Configure your project's <code>urls.py</code>:</p>
    107. 

  107. <div class="codehilite"><pre><span class="c"># /PROJECT/urls.py</span>
    108. 

  108. <span class="n">urlpatterns</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="s">&#39;&#39;</span><span class="p">,</span>
    109. 

  109.     <span class="c"># …</span>
    110. 

  110.     <span class="p">(</span><span class="s">r&#39;^hg/&#39;</span><span class="p">,</span> <span class="n">include</span><span class="p">(</span><span class="s">&#39;django_hg.urls&#39;</span><span class="p">)),</span>
    111. 

  111. <span class="p">)</span>
    112. 

  112. </pre></div>
    113. 

  113. 

  114. 

  115. <p>That's it.</p>
    116. 

  116. <p>You can now run the django built-in webserver:</p>
    117. 

  117. <div class="codehilite"><pre><span class="nv">$ </span>python manage.py runserver
    118. 

  118. </pre></div>
    119. 

  119. 

  120. 

  121. <h2 id="usage">Usage</h2>
    122. 

  122. <h3 id="administration">Administration</h3>
    123. 

  123. <p>Repositories can be created in django_hg using the admin module within the
    124. 

  124. django admin site.</p>
    125. 

  125. <p>You can import a repository by putting it in the folder of your choice (public
    126. 

  126. or private) and then create a repository object with the same name in the admin.</p>
    127. 

  127. <p>Because django <code>SlugField</code> are restricted to letters, numbers, underscores and
    128. 

  128. hyphens, the name of the repository root folder must match these restrictions.</p>
    129. 

  129. <p>For exemple, <code>mozilla-1.9.1</code> is not a valid name, but <code>mozilla-1_9_1</code> is.</p>
    130. 

  130. <p>django_hg allows setting permissions to users throught an inline form. There's 3
    131. 

  131. roles <code>Read</code>, <code>Read/Write</code> and <code>Owner</code>. These roles are used for displaying
    132. 

  132. repositories in browsers and when handling commands like <code>clone</code>, <code>push</code> and
    133. 

  133. <code>pull</code>.</p>
    134. 

  134. <h3 id="public">Public</h3>
    135. 

  135. <h4 id="list">List</h4>
    136. 

  136. <p>django_hg lets you browse a list of repositories, depending of the user
    137. 

  137. permissions:</p>
    138. 

  138. <ul>
    139. 

  139. <li>If the user is anonymous, only public repositories are displayed.</li>
    140. 

  140. <li>If the user is authenticated, private repositories where the user has role are
    141. 

  141.   displayed, plus public ones.</li>
    142. 

  142. </ul>
    143. 

  143. <p>A search facility is available. Currently, search looks in repositories' title
    144. 

  144. and summary, but not in the source code or the changelog.</p>
    145. 

  145. <p>Results can also be filtered using current user permissions, so only
    146. 

  146. repositories he owned are displayed, for example.</p>
    147. 

  147. <h4 id="repository">Repository</h4>
    148. 

  148. <p>When accessing a repository, you can display 3 differents views:</p>
    149. 

  149. <ul>
    150. 

  150. <li>The <code>overview</code> view summarizes the repository, showing the latest changeset
    151. 

  151.   (aka <code>tip</code> in Mercurial, people involved in the project. This page will evolve
    152. 

  152.   in the next weeks to be raffined.</li>
    153. 

  153. <li>The <code>browse</code> view displays the repository at a given revision (<code>tip</code> by default)</li>
    154. 

  154. <li>The <code>changesets</code>view diplays the list of revisions of the repository.
    155. 

  155.   You can browse the repository at a given revision or display the changelog
    156. 

  156.   details.</li>
    157. 

  157. </ul>
    158. 

  158. <h4 id="file">File</h4>
    159. 

  159. <p>From the <code>browse</code> and the <code>changeset</code> views, repository files can be accessed:</p>
    160. 

  160. <ul>
    161. 

  161. <li>The <code>log</code> view displays changes history of the file.</li>
    162. 

  162. <li>The <code>view</code> view shows the file, depending of its mimetype:</li>
    163. 

  163. <li>If a <a href="http://pygments.org">Pygments [en]</a> lexer can be found, the file is displayed
    164. 

  164.     with syntax coloration</li>
    165. 

  165. <li>If the mimetype corresponds to a picture (PNG, GIF, JPEG) or a PDF, the file
    166. 

  166.     is displayed</li>
    167. 

  167. <li>Otherwise, you can download it or force the display a plain text.</li>
    168. 

  168. <li>The <code>diff</code> view will allow the comparison between two revisions, but is far
    169. 

  169.   from being operational yet.</li>
    170. 

  170. </ul>
    171. 

  171. <h3 id="hg-commands-clone-push-and-pull">Hg commands (clone, push and pull)</h3>
    172. 

  172. <p>django_hg supports <code>clone</code>, <code>push</code> and <code>pull</code> over HTTP throught django,
    173. 

  173. including authentication.</p>
    174. 

  174. <h2 id="templating">Templating</h2>
    175. 

  175. <p>django_hg tries to follow
    176. 

  176. <a href="http://ericholscher.com/projects/django-conventions/app/">django reusable apps conventions [en]</a> in naming of
    177. 

  177. blocks.</p>
    178. 

  178. <p>A simple CSS is provided in the <code>site_media</code> directory. Feel free to</p>
    179. 

  179. <h2 id="deployment">Deployment</h2>
    180. 

  180. <p>Because django_hg relies on wsgi objects to performs Mercurial commands, django
    181. 

  181. must be deployed throught <a href="http://docs.djangoproject.com/en/1.0/howto/deployment/modwsgi/">mod_wsgi [en]</a>.</p>
    182. 

  182. <p>The Apache vhost configuration must contains the following directive in
    183. 

  183. order to <a href="http://www.arnebrodowski.de/blog/508-Django,-mod_wsgi-and-HTTP-Authentication.html">pass authentication [en]</a> to django:</p>
    184. 

  184. <div class="codehilite"><pre><span class="nb">WSGIPassAuthorization</span> <span class="k">On</span>
    185. 

  185. </pre></div>
    186. 

  186. 

  187. 

  188. <h2 id="to-dos">To-dos</h2>
    189. 

  189. <ul>
    190. 

  190. <li>Add missing features such as search in list, changesets, filelog</li>
    191. 

  191. <li><code>diff</code> and <code>archive</code></li>
    192. 

  192. <li>Add Ajax browsing for the repository</li>
    193. 

  193. </ul>
    194. 

  194. <h2 id="requirements">Requirements</h2>
    195. 

  195. <ul>
    196. 

  196. <li><a href="http://python.org/">Python 2.5+ [en]</a></li>
    197. 

  197. <li><a href="http://selenic.com/mercurial/">Mercurial 1.2 [en]</a></li>
    198. 

  198. <li><a href="http://djangoproject.com/">django 1.0.2 [en]</a></li>
    199. 

  199. <li><a href="http://pygments.org">Pygments [en]</a></li>
    200. 

  200. </ul>
    201. 

  201. <p>For deployement:</p>
    202. 

  202. <ul>
    203. 

  203. <li><a href="http://httpd.apache.org/">Apache 2.2 [en]</a></li>
    204. 

  204. <li><a href="http://code.google.com/p/modwsgi/">mod_wsgi [en]</a></li>
    205. 

  205. <li><a href="http://www.mysql.com/">MySQL [en]</a> or <a href="http://www.postgresql.org/">PostgreSQL [en]</a></li>
    206. 

  206. </ul>
    207. 

  207.       </div>
    208. 

  208.     </div>
    209. 

  209. </body>
    210. 

  210. </html>
    211. 

  211.