Documentation project » History » Revision 40
Revision 39 (Nancy Ouyang, 02/17/2015 09:37 PM) → Revision 40/42 (Tom Clegg, 08/10/2015 08:33 PM)
h1. Documentation project The documentation project is a part of the overall Arvados project. The output from this project forms the official documentation at "http://doc.arvados.org":http://doc.arvados.org. It is also included in the Arvados source tree. h2. Guides There are six guides that are being developed to support the use of Arvados: * "Getting Started":http://doc.arvados.org/start/ - Quickstart and overview of Arvados (what it is, who it's for, and key features). * "User Guide":http://doc.arvados.org/user/ - Introductory and tutorial materials for building analysis or web applications using Arvados. * "SDK Reference":http://doc.arvados.org/sdk/ - Details about the accessing Arvados from various programming languages. * "API Reference":http://doc.arvados.org/api/ - REST API methods and resources, the MapReduce job execution environment, permission model, etc. * "Admin Guide":http://doc.arvados.org/admin/ - Instructions to system administrators for maintaining an Arvados installation. * "Install Guide":http://doc.arvados.org/install/ - How to install and configure Arvados on the cloud management platform of your choice. A web version of the documentation is available at http://doc.arvados.org. h2. Documentation Project The Arvados documentation is written in Markdown, Textile, and HTML. The source code is in the @doc@ directory in the Arvados source tree. We use Jekyll to render HTML pages. h2. Contributing Bugs in the documentation can be submitted as "issues":/projects/arvados/issues. If you'd like to fix documentation bugs yourself, or to otherwise contribute to the documentation, clone the Arvados source repository, edit, and send pull requests just as you would when contributing program source code. We do not yet maintain a separate documentation mailing list, so we encourage documentation contributors to join the main developer mailing list. References for contributors: * "Markdown syntax":http://daringfireball.net/projects/markdown/syntax * "Textile syntax":http://redcloth.org/textile * "Zenweb":http://www.zenspider.com/projects/zenweb.html * "Liquid for designers":https://github.com/shopify/liquid/wiki/liquid-for-designers (template engine) Contributor quick-start: # Fork the arvados repository on github # Clone the repository and set up the preprocessor #* <pre><code>git clone git://github.com/<b>your_github_username</b>/arvados.git git://github.com/curoverse/arvados.git cd arvados/doc bundle install </code></pre> rake # Generate html (it documentation will appear be generated in @.site/@) and start an http server with your local copy .site/ #* <pre><code>rake rake run </code></pre> # Preview Note: The repository is only a few megabytes in size. You can now preview it in your browser at http://localhost:8000 . To generate Python SDK docs, install @epydoc@ and @arvados-python-client@ before running @rake@ in @arvados/doc@: <pre><code>sudo apt-get install python-pip python-virtualenv virtualenv /tmp/z source /tmp/z/bin/activate PATH=/tmp/z/bin:$PATH pip install epydoc arvados-python-client rake </code></pre> When you want to start making changes to the site, do so on a branch. If you'd like to follow our development process, create or pick an existing issue. For documentation purposes, https://arvados.org/issues/4926 is a safe bet. Note the issue number: *4926*. Then, # Fork the arvados repository on github # Make a feature branch # <pre><code>git checkout -b 4926-some-description</code></pre> 4926-some-description # Make (make your changes to the documentation documentation) git status # Preview your changes with @git status@, @git diff@, etc. shows you what files have changed # Add and commit the Next, git add [the files you want to include in the update. For example: example...] # <pre><code>git git add _config.yml _includes/_navbar_top.liquid _layouts/default.html.liquid index.html.liquid git commit -m "4926: Added foobar to barfoo" </code></pre> git remote add curoverse git@git.curoverse.com:arvados.git # Push the branch to your github account <pre><code>git git push git@github.com:<b>your_github_username</b>/arvados.git curoverse 4926-getting-started:4926-getting-started </code></pre> # Go to https://github.com and create The last command will throw “fatal” error if you’re pushing a pull request new branch, e.g. “remote: fatal: Invalid revision range". This can be safely ignored. We like Additionally, if you get a 403 error, email support@curoverse.com to see commit messages that start with an issue number (if applicable) and describe what request write permissions on the new code _does_, like this: * "1234: Explain it's important to install foo before baz." * "1234: Update foo example to use new bar feature." Arvados repository. Less-good messages: * "Improve docs." * "Incorporate review feedback." h3. Code Review Next, get it reviewed reviewed! After logging in to Arvados Redmine (http://arvados.org), add it as a subtask under the appropriate issue. Story/issue 4926 is a safe bet. https://arvados.org/issues/4926 If you don't see and merged! "Add" link (shown below) on the subtasks on the issue We should !subtask.png! email support@curoverse.com to get notified when new PRs arrive, but if you'd like permissions in the Redmine issue tracker to move things add tasks. Call the task something along faster we'll be happy the lines of "Review branch: 4926-some-description". The task / branch should get reviewed shortly. If not, email support@curoverse.com . h3. Merging to hear master branch You've gotten the green light from you one code review to merge your branch into master. Now what? <pre><code>git checkout master git merge --no-ff 4926-some-description git push origin master </code></pre> The merge message needs to include some special syntax or more of else your merge commit will be rejected: <pre><code>refs #4926 Merge branch '4926-some-description'</code></pre> Alternatively, if your merge closes issue(s) (for instance, the following ways: "review branch" subtask you created), use something like * visit our IRC channel <pre><code>closes #5090 Merge branch '4926-some-description'</code></pre> * send email to support@curoverse.com * Visit our "redmine This will mark the issue tracker":http://arvados.org as resolved in the redmine issue tracker and add a review subtask under the appropriate issue, if applicable -- just enter commit log number to the subject "review 4926-some-description" ticket, allow developers to easily cross-reference the git repository and we'll know what it means. redmine. You can reference or close multiple issues at once <pre><code>closes #5090, #5092 Merge branch '4926-some-description'</code></pre> If no issue was created, use "no issue #" like so <pre><code>Fix typo No issue #</code></pre> After that, your code changes should take effect on the next deploy. h3. Important files and folders These are located in the arvados/doc directory. * */css/* By convention, we store all the CSS files here. * */js/* By convention, we store all the Javascript files here. * */_includes/_navbar_top.liquid* These describe the top navigation bar, if you are adding or renaming sections * */_config.yml* This file describes the order of pages in the left navigation bar. * */_layouts/default.html.liquid* If you wish to include new CSS or Javascript files (for instance, in /css or /js) across the whole site, do so here.