org.eclipse.egit.doc/help/EGit/Contributor_Guide/Documentation.html

   1 <?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3         <head>
   4                 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
   5                 <title>EGit Contributor Guide - Documentation</title>
   6                 <link type="text/css" rel="stylesheet" href="../../book.css"/>
   7         </head>
   8         <body>
   9                 <table class="navigation" style="width: 100%;" border="0" summary="navigation">
  10                         <tr>
  11                                 <th style="width: 100%" align="center" colspan="3">Documentation</th>
  12                         </tr>
  13                         <tr>
  14                                 <td style="width: 20%" align="left">
  15                                         <a href="Builds.html" title="Builds">
  16                                                 <img alt="Previous" border="0" src="../../images/prev.gif"/>
  17                                         </a>
  18                                 </td>
  19                                 <td style="width: 60%" align="center"></td>
  20                                 <td style="width: 20%" align="right">
  21                                         <a href="Tests.html" title="Tests">
  22                                                 <img alt="Next" border="0" src="../../images/next.gif"/>
  23                                         </a>
  24                                 </td>
  25                         </tr>
  26                         <tr>
  27                                 <td style="width: 20%" align="left" valign="top">Builds</td>
  28                                 <td style="width: 60%" align="center"></td>
  29                                 <td style="width: 20%" align="right" valign="top">Tests</td>
  30                         </tr>
  31                 </table><hr class="navigation-separator"/>
  32                 <h1 id="Documentation">Documentation</h1>
  33                 <h2 id="JGit_3">JGit</h2>
  34                 <p>The JGit project generates a project report and javadocs using a Maven site. This Maven site is deployed to
  35                         <a href="http://download.eclipse.org/jgit/site/$" target="egit_external">http://download.eclipse.org/jgit/site/$</a>{project.version}.
  36                         E.g.
  37                         <a href="http://download.eclipse.org/jgit/site/3.5.0.201409260305-r/" target="egit_external">http://download.eclipse.org/jgit/site/3.5.0.201409260305-r/</a>
  38                 </p>
  39                 <p>Generating the site:</p>
  40                 <pre><b>$ mvn site:site</b>
  41 </pre>
  42                 <p>Staging the site locally under ./target/staging:</p>
  43                 <pre><b>$ mvn site:stage</b>
  44 </pre>
  45                 <p>If you can connect to build.eclipse.org over ssh (ask webmaster if you are a committer and need ssh access) you can deploy a local build of the site:</p>
  46                 <pre><b>$ mvn site:deploy</b>
  47 </pre>
  48                 <p>The site is deployed under
  49                         <a href="http://download.eclipse.org/jgit/site/$" target="egit_external">http://download.eclipse.org/jgit/site/$</a>{project.version}
  50                 </p>
  51                 <p>To select the ssh key to use for deploying over ssh add the following section to your Maven settings.xml:</p>
  52                 <pre>&lt;server&gt;
  53      &lt;id&gt;jgit.website&lt;/id&gt;
  54      &lt;username&gt;username&lt;/username&gt;
  55      &lt;privateKey&gt;${user.home}/.ssh/id_rsa&lt;/privateKey&gt;
  56      &lt;password&gt;{&lt;encrypted passphrase&gt;}&lt;/password&gt;
  57      &lt;filePermissions&gt;664&lt;/filePermission&gt;
  58      &lt;directoryPermissions&gt;775&lt;/directoryPermissions&gt;
  59      &lt;configuration&gt;&lt;/configuration&gt;
  60 &lt;/server&gt;
  61 </pre>
  62                 <p>Password encryption for Maven is described in
  63                         <a href="https://maven.apache.org/guides/mini/guide-encryption.html" target="egit_external">https://maven.apache.org/guides/mini/guide-encryption.html</a>
  64                 </p>
  65                 <p>To deploy the site from JGit HIPP (Hudson) at
  66                         <a href="https://hudson.eclipse.org/jgit/" target="egit_external">https://hudson.eclipse.org/jgit/</a> enable the Maven profile
  67                         <b>build-server</b> and add the Maven goals
  68                         <b>site:site site:deploy</b>.
  69                 </p>
  70                 <p>If you uploaded the site for a new release update the index
  71                         /home/data/httpd/download.eclipse.org/jgit/docs/latest/apidocs/index.html
  72                         to refer to the new release's site.</p>
  73                 <h2 id="EGit_3">EGit</h2>
  74                 <p>The EGit project sources its documentation from the wiki and generates Eclipse help content from it (under the covers, we are using
  75                         <a href="http://wiki.eclipse.org/Mylyn/WikiText" target="egit_external">Mylyn WikiText</a> to make this possible). This significantly lowers the barrier for people to contribute documentation to the EGit project. To contribute documentation, simply modify the
  76                         <a href="http://wiki.eclipse.org/EGit/User_Guide" target="egit_external">EGit User's Guide</a>. Have a look at the
  77                         <a href="http://wiki.eclipse.org/DocumentationGuidelines/StyleGuidelines" title="DocumentationGuidelines/StyleGuidelines" target="egit_external">Style Guidelines</a> and
  78                         <a href="http://wiki.eclipse.org/Eclipse_Doc_Style_Guide" title="Eclipse_Doc_Style_Guide" target="egit_external">Eclipse Documentation Style Guide</a> to get some guidance on how to write good documentation. More on that can be found
  79                         <a href="http://wiki.eclipse.org/DocumentationGuidelines" title="DocumentationGuidelines" target="egit_external">here</a>.
  80                 </p>
  81                 <p>The documentation is contained in the
  82                         <b>org.eclipse.egit.doc</b> plug-in. The
  83                         <b>build-help.xml</b> drives the generation of the help content. It is integrated into the maven build. The regular maven build of
  84                         <b>org.eclipse.egit.doc</b>
  85                 </p>
  86                 <pre><b>$ mvn clean install</b>
  87 </pre>
  88                 <p>will only package the help content committed to the egit repository. To update the help content by downloading the latest documentation from the wiki run</p>
  89                 <pre><b>$ mvn clean install -Dupdate.egit.doc</b>
  90 </pre>
  91                 <p>Don't forget to check all the generated help pages and especially all hyperlinks and images before pushing the updated help to the code review system for inclusion into the continuous build.</p>
  92                 <p>The aim is to generate new documentation every month or so (or just on demand). If you're making big changes or want the documentation refreshed, please let us know on the egit-dev mailing list.</p>
  93                 <p>
  94                         <br/>
  95                 </p><hr class="navigation-separator"/>
  96                 <table class="navigation" style="width: 100%;" border="0" summary="navigation">
  97                         <tr>
  98                                 <td style="width: 20%" align="left">
  99                                         <a href="Builds.html" title="Builds">
 100                                                 <img alt="Previous" border="0" src="../../images/prev.gif"/>
 101                                         </a>
 102                                 </td>
 103                                 <td style="width: 60%" align="center">
 104                                         <a href="Contributor-Guide.html" title="EGit Contributor Guide">
 105                                                 <img alt="EGit Contributor Guide" border="0" src="../../images/home.gif"/>
 106                                         </a>
 107                                 </td>
 108                                 <td style="width: 20%" align="right">
 109                                         <a href="Tests.html" title="Tests">
 110                                                 <img alt="Next" border="0" src="../../images/next.gif"/>
 111                                         </a>
 112                                 </td>
 113                         </tr>
 114                         <tr>
 115                                 <td style="width: 20%" align="left" valign="top">Builds</td>
 116                                 <td style="width: 60%" align="center"></td>
 117                                 <td style="width: 20%" align="right" valign="top">Tests</td>
 118                         </tr>
 119                 </table>
 120         </body>
 121 </html>