The "documentation" project has been started, has minimum information to be able to be built on a linux operating system
Project: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/commit/c6196d00 Tree: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/tree/c6196d00 Diff: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/diff/c6196d00 Branch: refs/heads/master Commit: c6196d00e037ff123ac9b75ea9a139dd2ca28ad5 Parents: ad7ca4d Author: Evan Hughes <ehu...@gmail.com> Authored: Sat May 9 22:41:42 2015 +1000 Committer: Evan Hughes <ehu...@gmail.com> Committed: Sat May 9 22:41:42 2015 +1000 ---------------------------------------------------------------------- source/documentation/About/index.rst | 32 +++++++++++ source/documentation/Building/index.rst | 50 +++++++++++++++++ source/documentation/Contributing/index.rst | 23 ++++++++ source/documentation/Installing/index.rst | 57 ++++++++++++++++++++ source/documentation/Introduction/index.rst | 43 +++++++++++++++ source/documentation/conf.py | 5 +- .../example/oneFileToRuleThemAll.rst | 33 ------------ source/documentation/index.rst | 38 +++++++------ source/general/skeleton.rst | 19 +++++++ 9 files changed, 249 insertions(+), 51 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/c6196d00/source/documentation/About/index.rst ---------------------------------------------------------------------- diff --git a/source/documentation/About/index.rst b/source/documentation/About/index.rst new file mode 100644 index 0000000..becf3ec --- /dev/null +++ b/source/documentation/About/index.rst @@ -0,0 +1,32 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +About +===== + +Documents in Development +------------------------ + + The development effort is in the process of developing multiple documents to separate the aspects of Apache Wave + into reasonable size. This includes the development of: + + * This document; a setup and overview of the documentation system. + * User Manual; provided to help users with the wave client. + * Developer Doc; a resource with technical information needed to contribute to the Apache Wave development. + * Api Doc; reference for the api's provided to 3rd party developers. + * Protocol Specification; technical resource to explain and design the protocols in use by Apache Wave. + http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/c6196d00/source/documentation/Building/index.rst ---------------------------------------------------------------------- diff --git a/source/documentation/Building/index.rst b/source/documentation/Building/index.rst new file mode 100644 index 0000000..e60fcf7 --- /dev/null +++ b/source/documentation/Building/index.rst @@ -0,0 +1,50 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +Building +======== + +While in the root source directory ``/source`` the documentation can be built using make. + +.. code-block:: python + + make <build-option> + +where <build-option> is one of these available options: + + ============== ========================================================== + <build-option> Description + ============== ========================================================== + help displays the help menu + clean clears the build directory (deletes all files under build) + all produces all pdf and html docs + all-pdf produces all pdf docs + all-html produces all html docs + doc-html produces "documentation" html doc + doc-pdf produces "documentation" pdf doc + developer-html produces "developer" html doc + developer-pdf produces "developer" pdf doc + api-html produces "api" html doc + api-pdf produces "api" pdf doc + manual-html produces "manual" html doc + manual-pdf produces "manual" pdf doc + protocol-html produces "protocol" html doc + protocol-pdf produces "protocol" pdf doc + ============== ========================================================== + +The output will be available in ``/build/<project name>/html`` or ``/build/<project name>/pdf`` + http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/c6196d00/source/documentation/Contributing/index.rst ---------------------------------------------------------------------- diff --git a/source/documentation/Contributing/index.rst b/source/documentation/Contributing/index.rst new file mode 100644 index 0000000..ccedd84 --- /dev/null +++ b/source/documentation/Contributing/index.rst @@ -0,0 +1,23 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +Contributing +============ + +.. todo:: + * Add the more common ReST syntax that will be used in these documents. + * Add information about submitting pull requests and the mailing list \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/c6196d00/source/documentation/Installing/index.rst ---------------------------------------------------------------------- diff --git a/source/documentation/Installing/index.rst b/source/documentation/Installing/index.rst new file mode 100644 index 0000000..ab69683 --- /dev/null +++ b/source/documentation/Installing/index.rst @@ -0,0 +1,57 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +Installing +========== + +It is assumed knowledge that your able to *clone/fork* the **Git** repository containing the project. This repository can be +found publicly at https://github.com/apache/incubator-wave-docs . + +The project also uses the pull request development workflow. At tutorial of this workflow can be found here +https://www.atlassian.com/git/tutorials/making-a-pull-request . + +.. topic:: Requirements + + * Python 2.7+ + * Pip + * make + + +Installing Sphinx +----------------- + + Sphinx is a easy to use documentation system which is most notably used for the python documentation. It was chosen + by the project to be used due to its ease of use and available outputs (Html & Pdf). This allows print out + publications to be made and a large availability for online and offline use. + + Sphinx is recommended to be installed through pip: + + .. code-block:: python + :linenos: + + pip install sphinx + + **Latex Pdf additional Packages** + + These packages may be required when building the pdf version of the documents. + + Linux: + Debian Based: + +.. code-block:: python + + apt-get install texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/c6196d00/source/documentation/Introduction/index.rst ---------------------------------------------------------------------- diff --git a/source/documentation/Introduction/index.rst b/source/documentation/Introduction/index.rst new file mode 100644 index 0000000..b4bf6c2 --- /dev/null +++ b/source/documentation/Introduction/index.rst @@ -0,0 +1,43 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +Introduction +============ + +What are we doing? +------------------ + + This document is being provided to help everyday amateur to advanced programmers contribute to the Apache Wave + documentation. If you would like to learn more about apache wave itself please visit + https://incubator.apache.org/wave/ . + + This document provides information in setting up and contributing to the documentation process using the Sphinx + project and ReStructured Text. This is also provided as an example for the other documents in the Git repository + . + +Who is doing this? +------------------ + + The Apache Wave project is being developed in the Apache Foundations Incubator and comprises of volunteers. + + +Why are we doing this? +---------------------- + + The Apache Wave project has been in the incubator since 2010 and has had a lacking of documentation or + development progress due to its large complexity. By making the documentation process easier the project hopes + to remove the barriers for new developers to start contributing. http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/c6196d00/source/documentation/conf.py ---------------------------------------------------------------------- diff --git a/source/documentation/conf.py b/source/documentation/conf.py index 5571090..ee7b61e 100644 --- a/source/documentation/conf.py +++ b/source/documentation/conf.py @@ -225,8 +225,11 @@ htmlhelp_basename = 'ApacheWaveincubatingdoc' # -- Options for LaTeX output --------------------------------------------- latex_elements = { +'classoptions': ',oneside', +'babel' : '\\usepackage[english]{babel}', + # The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', +'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/c6196d00/source/documentation/example/oneFileToRuleThemAll.rst ---------------------------------------------------------------------- diff --git a/source/documentation/example/oneFileToRuleThemAll.rst b/source/documentation/example/oneFileToRuleThemAll.rst deleted file mode 100644 index 7178115..0000000 --- a/source/documentation/example/oneFileToRuleThemAll.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - -.. http://www.apache.org/licenses/LICENSE-2.0 - -.. Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -The One File to Rule Them All -============================= - -Paragraphs: - Everybody *Loves* paragraphs, except people who do **not** love ``paragraphs`` of course. - -Tables: - - ===== ===== ======= - A B A and B - ===== ===== ======= - False False False - True False False - False True False - True True True - ===== ===== ======= \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/c6196d00/source/documentation/index.rst ---------------------------------------------------------------------- diff --git a/source/documentation/index.rst b/source/documentation/index.rst index 998a45a..8e735a0 100644 --- a/source/documentation/index.rst +++ b/source/documentation/index.rst @@ -1,27 +1,31 @@ -.. Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at -.. http://www.apache.org/licenses/LICENSE-2.0 +.. http://www.apache.org/licenses/LICENSE-2.0 -.. Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. Apache Wave (incubating)'s documentation ======================================== -Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 2 + :includehidden: - example/oneFileToRuleThemAll + Introduction/index + About/index + Installing/index + Contributing/index + Building/index \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/c6196d00/source/general/skeleton.rst ---------------------------------------------------------------------- diff --git a/source/general/skeleton.rst b/source/general/skeleton.rst new file mode 100644 index 0000000..79ef539 --- /dev/null +++ b/source/general/skeleton.rst @@ -0,0 +1,19 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +Title +===== \ No newline at end of file
