From fc50b198b9f8f30325aa1a4315bef98de98e5e25 Mon Sep 17 00:00:00 2001 From: Utkarsh Ayachit Date: Thu, 2 Apr 2015 17:52:15 -0400 Subject: [PATCH] Adding README and CONTRIBUTING instructions. --- .gitignore | 2 ++ CONTRIBUTING.md | 59 +++++++++++++++++++++++++++++++++ README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 147 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 README.md diff --git a/.gitignore b/.gitignore index 12a5b8a..1a85c2e 100644 --- a/.gitignore +++ b/.gitignore @@ -11,5 +11,7 @@ !CMake/* !ParaView/* !ParaViewCatalyst/* +!README.md +!CONTRIBUTING.md ParaView/Extras .* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6fbd4b5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +Contributing to ParaView Guide - Community Edition +================================================== + +Contritbutions are always welcome. There are several ways of contributing. + +1. You can may your contributions through **[merge requests][]** made to this [GitLab][] +repository. + +2. You can also post your edits to the [Mailing List][], coordinating with any of +the ParaView developers to get your updates in. + +3. Alternatively, you can also post your text changes directly on a new issue on the +[issue tracker] or in a [snippet]. + +For those interested in making changes through the **[merge requests][]**, the workflow +is as follows: + +1. Register with [GitLab Access] to create an account and select a user name. + +2. [Fork ParaViewGuide-CE][] into your user's namespace on GitLab. + +3. Clone the repository: + + $ git clone https://gitlab.kitware.com/paraview/paraview-guide-ce.git ParaViewGuide + $ cd ParaViewGuide + The main repository will be configured as your `origin` remote. + +4. Add your fork as a the `gitlab` remote. + + $ git remote add gitlab https://gitlab.kitware.com/username/paraview-guide-ce.git + You can use configure the remote to use SSH access instead, if needed. + +5. Edit files and create commits (repeat as needed): + + $ git checkout -b my-topic origin/master + $ edit file1 file2 file3 + $ git add file1 file2 file3 + $ git commit + +6. Push commits in your topic branch to your fork in GitLab: + + $ git push gitlab HEAD + +7. Visit your fork in GitLab, browse to the "**Merge Requests**" link on the + left, and use the "**New Merge Request**" button in the upper right to + create a Merge Request. + +Please refer to [ContributorNotes.tex][] to guidelines on contributing content +for the guide. + +[merge requests]: https://gitlab.kitware.com/paraview/paraview-guide-ce/merge_requests +[GitLab]: https://gitlab.kitware.com/paraview/paraview-guide-ce/ +[Mailing List]: http://www.paraview.org/mailing-lists/ +[ParaView Git]: https://gitlab.kitware.com/paraview/paraview/blob/master/CONTRIBUTING.md +[ContributorNotes.tex]: ParaView/ContributorNotes.tex +[GitLab Access]: https://gitlab.kitware.com/users/sign_in +[Fork ParaViewGuide-CE]: https://gitlab.kitware.com/paraview/paraview-guide-ce/fork/new +[issue tracker]: https://gitlab.kitware.com/paraview/paraview-guide-ce/issues +[snippet]: https://gitlab.kitware.com/paraview/paraview-guide-ce/snippets \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..9ceda34 --- /dev/null +++ b/README.md @@ -0,0 +1,86 @@ +The ParaView Guide (Community Edition) +====================================== + +Introduction +------------ + +This repository contains the *LaTeX* files for the **Community Edition** of +**The ParaView Guide** and **ParaView Catalyst User's Guide**. + +You can download the PDF for the latest release or buy a printed version of +**The ParaView Guide** [online][ParaView Books]. In addition to the chapters in +the *Community Edition*, the printed versions include 3 extra chapters that +cover using ParaView for CFD analysis, AMR processing, and case-studies. + +Editions +--------- + +The guide will be updated with each significant release of ParaView. +Versions of the guide for specific ParaView releases starting with ParaView 4.3.1 +can be found [here][tags]. + +[ParaView Books]: http://www.paraview.org/paraview-guide/ +[tags]: https://gitlab.kitware.com/paraview/paraview-guide-ce/tags + +License +------- + +**The ParaView Guide (Community Edition)** and +**ParaView Catalyst User's Guide** are released under [CC BY 4.0][]. + +The printed editions of **The ParaView Guide** are released under [CC BY-ND 4.0][]. +[CC BY 4.0]: http://creativecommons.org/licenses/by/4.0/ +[CC BY-ND 4.0]: http://creativecommons.org/licenses/by-nd/4.0/ + +Build Instructions +------------------ + +This is **CMake** based project and can be built similar to ParaView. We use **LaTeX** +for typesetting the guides. Thus, unless you are familiar with setting up LaTeX on your system, +you may want to simply download the pregenerated PDF from the [ParaView homepage][ParaView Books]. + +1. Clone the repository + + $ git clone https://gitlab.kitware.com/paraview/paraview-guide-ce.git ParaViewGuide + The main repository will be configured as your `origin` remote. + +2. Run CMake. This step requires you have LaTeX (and necessary modules) installed + on your system. You can turn **ENABLE_PARAVIEW_GUIDE** (default: ON) and/or + **ENABLE_CATALYST_USERS_GUIDE** (default: OFF) ON or OFF based on your preference. + On Unix-based systems, the steps are: + + $ mkdir ParaViewGuildBuild + $ cmake /ParaViewGuide + $ make + +3. On successful build, the **ParaView/ParaViewUsersGuide.pdf** and/or + **ParaViewCatalyst/ParaViewCatalystUsersGuide.pdf** will be generated based + on the options you chose in Step 2. + +Note that Step 2 can take a long time, especially *rendering* the images. +To speed things, you can edit [ParaViewUsersGuide.tex][] file to change +the documentclass mode to `[draft]`. + + \documentclass[draft]{InsightSoftwareGuide} +This will generate the the draft PDF without any images. +[ParaViewUsersGuide.tex]: ParaView/ParaViewUsersGuide.tex + +Reporting Bugs +--------------- + +1. If you have a edits or updates, please see [CONTRIBUTING.md][] document. + +2. For build issues and other inquiries, please join the + [ParaView Mailing List][]. + +2. You can also report issues or errata on the [issue tracker][]. + +[issue tracker]: https://gitlab.kitware.com/paraview/paraview-guide-ce/issues +[ParaView Mailing List]: http://www.paraview.org/mailing-lists/ + +Contributing +------------ + +See [CONTRIBUTING.md][] for instructions to contribute. + +[CONTRIBUTING.md]: CONTRIBUTING.md -- GitLab