Adding developer documentation #66

PrasadBabarendaGamage · 2017-03-12T08:07:48Z

This outline is outdated, see the latest outline on issue #65

This documentation has been built along with the OpenCMISS website and it builds fine with no errors. There are warnings regarding figure numbering, however, these will be addressed in another documentation issue as they are not critical.

Key/simplified steps

making your own topic branch

(completed) Guidelines for contributing to OpenCMISS
(completed) Development Setup
(placeholder) Building OpenCMISS for developers
- The procedure for using the manage repo to build OpenCMISS from source (described in the Further Details section of the existing Building OpenCMISS Libraries From Source needs to be moved here.
- The simpler procedure for getting started using the setup repo (i.e. for users) can be moved to a getting started section.
(placeholder) Coding Standard
- Need to add separate sections for,
- Fortran [Here is the link to coding style in Iron's doxygen documentation]
  (https://github.com/OpenCMISS/cm/pull/172/files).
- C, C++, python (link to Google style guide for these)
(placeholder) Documenting your code
- How to add documentation to code simple doxygen comments
- How to add sphinx documentation
- Among other things, we need to move or link the information in the 'Guide to contributing documentation' contained in the CONTRIBUTE.md of the OpenCMISS/documentation repo here.
(placeholder) Testing code
- testing yourself
- testing your fork using Jenkins (optional). Need to add documentation on how to use Jenkins.
- mention that the code will be automatically tested each time a commit is added to a pull request
(completed) Contributing
(completed) Review Process
(placeholder) API Documentation
- This section can be renamed 'technical documentation'. Need to add links to API docs that are currently in the Technical documentation section of the OpenCMISS website.

Addresses issue #65

Merge

1. **(completed)** Guidelines for contributing to OpenCMISS 2. **(completed)** Development Setup 3. **(placeholder)** Building OpenCMISS for developers - The procedure for using the manage repo to build OpenCMISS from source (described in the [Further Details section of the existing Building OpenCMISS Libraries From Source](http://staging.opencmiss.org/documentation/building/index.html) needs to be moved here. - The simpler procedure for getting started using the setup repo (i.e. for users) can be moved to a getting started section. 4. **(placeholder)** Coding Standard - Need to add separate sections for Iron and Zinc. - [Here is the link to coding style in Iron's doxygen documentation](https://github.com/OpenCMISS/cm/pull/172/files). 5. **(placeholder)** Documenting your code - Among other things, we need to move or link the information in the 'Guide to contributing documentation' contained in the [CONTRIBUTE.md of the OpenCMISS/documentation repo ](https://github.com/OpenCMISS/documentation/blob/develop/CONTRIBUTE.md) here. 6. **(placeholder)** Submitting Code for Testing - Need to add documentation on how to use Jenkins 7. **(completed)** Contributing 8. **(completed)** Review Process 9. **(placeholder)** API Documentation - This section can be renamed 'technical documentation'. Need to add links to API docs that are currently in the [Technical documentation section of the OpenCMISS website](http://staging.opencmiss.org/documentation.html). addresses issue OpenCMISS#65

PrasadBabarendaGamage · 2017-03-12T08:44:36Z

contribute/index.rst

+.. toctree::
+   :maxdepth: 1
+
+   dev_guidelines


The style used in the heading of these rst documents are inconsistent. Some use sentence case, others use title case.

nickerso

looks like a good starting point. would be good to get these changes up on staging so we have a consistent reference point for future discussion.

Updating GitHub issue descriptions on website based on pull request 66 reviewer comments.(OpenCMISS/documentation#66) Addresses issue OpenCMISS#65

PrasadBabarendaGamage · 2017-03-27T10:42:16Z

Hi guys, Andre has reviewed/approved this pull request, hoping if we could pull it in into the develop branch. This will automatically trigger an update to the staging.opencmiss.org website.

hsorby

The only part that I object to is the loss of the TL;DR section. I feel that having the commands first before any text is the best way to capture users who just want instructions.

PrasadBabarendaGamage · 2017-03-30T22:31:32Z

Can add the TL;DR section in again in another pull request (but we probably need to define the term as some noobs like myself have no idea what that means and it becomes confusing).

PrasadBabarendaGamage · 2017-03-30T22:40:40Z

Actually might be better to add the TL;DR section to another page called Quick start. So that it does not confuse newbie developers.

hsorby · 2017-03-30T22:55:58Z

I really don't think we need to define the term, if people can't figure it out (and google is pretty useful for this sort of stuff) then they are going to have trouble using Iron and Zinc.

chrispbradley · 2017-03-30T23:09:36Z

We shouldn't have terms like TL;DR in the web documentation or indeed any other internet lingo, amusing or not. There is a significant academic side to the project and many people from grant reviewers and collaborators look at the site. The site should be able to pass the 60 yo professor reading it test. I'm afraid TL;DR does not really pass this test.

rchristie · 2017-03-30T23:22:42Z

I'm also against TL;DR and prefer 'Quick Start' or similar.

rchristie · 2017-04-04T21:07:55Z

building/index.rst

 cmake --build .

-The above instructions will not work if the basic requirements listed in :ref:`requirements` is not met.  If executing these commands from a Visual Studio command prompt on a Windows machine the penultimate command may need to by adpated to include the generator required. For example if a 64 bit Visual Studio build is desired the command would be adapted to::
+If executing these commands from a Visual Studio command prompt on a Windows machine the penultimate command may need to by adpated to include the generator required. For example if a 64 bit Visual Studio build is desired the command would be adapted to::


Typo: --> adapted

rchristie · 2017-04-04T21:10:48Z

contribute/dev_building.rst

+Building OpenCMISS for developers
+=================================
+
+** Coming soon**


Do not put empty sections in. This harks back to the early web 'under construction' icons which are not seen any more and for good reason: they look bad and are completely useless right up until the work is actually done. The correct place for noting future work is a new issue.

Added new issue for this #72

rchristie · 2017-04-04T21:15:22Z

contribute/dev_contribution.rst

+
+In addition, a **Platform** label may be used to identify the issue as specific to a given platform (Windows/Linux/OS X). **Milestone** labels may be used to project when a feature is expected to be complete and/or indicate the priority of a given issue. Higher priority issues will take precedence and therefore be assigned a more immediate (lower) milestone number.
+
+Topic Branch


Consistently call them feature branches, or topic branches if there is consensus for that name. Github has excellent documentation and calls them feature branch; I much prefer feature branch over topic branch.

rchristie · 2017-04-04T21:19:00Z

contribute/dev_contribution.rst

+   git fetch prime develop
+   git checkout develop # Not required if already on develop branch
+   git merge prime/develop
+   git checkout -b issue46


I would suggest we recommend users name their branches starting with the issue number followed by a word or words to succinctly describe it; 'issue' is redundant. Some examples I've used: 56_refactor_fe, 36_derivatives.

rchristie · 2017-04-04T21:20:41Z

contribute/dev_documentation.rst

+.. Contributing Documentation
+
+=====================
+Documenting your code


Remove this section. Put future tasks in separate issues.

Issue created for this #71

rchristie · 2017-04-04T21:22:41Z

contribute/dev_review_process.rst

+
+.. The Documentation Builder link (entry 2. in step 5.) will take you to the build for the documentation.  On this page you can see the steps taken to build the documentation.  In the last step of the build (step 7.) there is a link 'dox' (entry 2.) that will take you to the built documentation.
+
+**Coming soon: how to check documentation using Jenkins**


Stuck record. Future work belongs in separate issues, not littering our documentation.

rchristie · 2017-04-04T21:26:56Z

contribute/dev_setup.rst

+   - https://github.com/OpenCMISS/documentation
+   - https://github.com/OpenCMISS/website
+   - https://github.com/OpenCMISS/manage
+


These links should appear as just 'iron', 'zinc' etc. and link to the address.
Add repo cmake_modules.
I think it would be good to present this as a table with a second column describing in a minimally brief statement what the repository contains.

A new issue has been created for this #73

rchristie · 2017-04-04T21:28:19Z

contribute/dev_setup.rst

+
+   https://github.com/OpenCMISS
+
+The OpenCMISS organisation contains the git repositories for each component of OpenCMISS:


repositories for each of its components, documentation and tools:

rchristie · 2017-04-04T21:33:11Z

contribute/dev_setup.rst

+
+You now need to clone the selected repository to your PC.  Do this by going to your fork (in this example user *prasad*'s fork) at::
+
+   https://github.com/prasad/iron


I really don't like having an actual person's name here; keep credit in the git contribution record or a dedicated contributors page. Change 'prasad' to 'username' (which is what github calls it), and at the beginning define that it is to be substituted with your own username on github. You could alternatively write or emphasise it with italics.

rchristie · 2017-04-04T21:34:00Z

contribute/dev_setup.rst

+
+.. warning::
+
+   Don't try and clone this location. Substitute your GitHub username for *prasad*.


This is unnecessary if you said at the beginning that username stands for your user name.

rchristie · 2017-04-04T21:40:45Z

contribute/dev_setup.rst

+Now clone the repository::
+
+        cd <somewhere/you/keep/development/code>
+        git clone git@github.com:prasad/iron.git


We should keep our story consistent with setup: recommend making a top opencmiss folder (I call mine oc to keep paths short) and in it add a sub folder src, and clone your fork of iron there. This is where the setup script will clone iron etc. (admittedly it clones the prime repo by default, but you can switch to your own remote).
Did you know if you subsequently run setup or manage on the same opencmiss (or 'oc') folder it will discover and keep your sources for any components in the src folder? It's very convenient for rebuilding from scratch. This is the convenient way to get your own forks.

Just wondering if this would still work? Might be better if Hugh adds this to the build documentation.

rchristie · 2017-04-04T21:41:33Z

contribute/dev_technical.rst

@@ -0,0 +1,5 @@
+=================
+API Documentation


Added an issue for this #75

rchristie · 2017-04-04T21:41:40Z

contribute/dev_testing_code.rst

+.. Instructions for testing OpenCMISS code
+
+===========================
+Submitting Code for Testing


Added a new issue for this #74

rchristie · 2017-04-04T21:46:24Z

contribute/guidelines_for_iron_developers.rst

@@ -0,0 +1,100 @@
+========================================
+Guidelines for OpenCMISS-Iron Developers


Nothing in here is actually specific to Iron, and it repeats substantial portions of content that is elsewhere. Merge all new content into the respective sections above and remove.

This page is not explicitly linked to the website. As you suggest, this page can be removed once the any relevant information has been removed. Created a new github issue for this: #77

rchristie · 2017-04-04T21:54:23Z

contribute/dev_contribution.rst

+============
+
+If an issue does not exist for the required work (e.g. implementation of a feature, fixing of a bug), then create a new one.  The issue is the place to discuss the particulars related to the issue, discussions on determining the scope of the issue or clarification of any points that are unclear.
+


Add: Create the issue into issue list for the respective component repository it relates to. [What if it relates to multiple components? perhaps suggest creating an issue in each and adding a comment linking to the other e.g. cmlibs/zinc#60, as documented in github-secrets.]

PrasadBabarendaGamage added 4 commits February 14, 2017 00:51

Merge pull request #1 from OpenCMISS/develop

b6ff315

Merge

Adding guidelines for iron developers

42a43ad

Merge branch 'develop' into develop

1d16f37

PrasadBabarendaGamage commented Mar 12, 2017

View reviewed changes

nickerso approved these changes Mar 12, 2017

View reviewed changes

hsorby approved these changes Mar 29, 2017

View reviewed changes

rchristie reviewed Apr 4, 2017

View reviewed changes

hsorby merged commit 85d650a into OpenCMISS:develop May 1, 2017

PrasadBabarendaGamage mentioned this pull request May 6, 2017

Updating developer documentation #70

Merged

PrasadBabarendaGamage mentioned this pull request Jun 12, 2017

Simplify links on developer setup page #73

Open


		In addition, a Platform label may be used to identify the issue as specific to a given platform (Windows/Linux/OS X). Milestone labels may be used to project when a feature is expected to be complete and/or indicate the priority of a given issue. Higher priority issues will take precedence and therefore be assigned a more immediate (lower) milestone number.

		Topic Branch


		.. The Documentation Builder link (entry 2. in step 5.) will take you to the build for the documentation. On this page you can see the steps taken to build the documentation. In the last step of the build (step 7.) there is a link 'dox' (entry 2.) that will take you to the built documentation.

		Coming soon: how to check documentation using Jenkins


		https://github.com/OpenCMISS

		The OpenCMISS organisation contains the git repositories for each component of OpenCMISS:


		You now need to clone the selected repository to your PC. Do this by going to your fork (in this example user prasad's fork) at::

		https://github.com/prasad/iron


		.. warning::

		Don't try and clone this location. Substitute your GitHub username for prasad.

		@@ -0,0 +1,100 @@
		========================================
		Guidelines for OpenCMISS-Iron Developers

		============

		If an issue does not exist for the required work (e.g. implementation of a feature, fixing of a bug), then create a new one. The issue is the place to discuss the particulars related to the issue, discussions on determining the scope of the issue or clarification of any points that are unclear.

Adding developer documentation #66

Adding developer documentation #66

Uh oh!

Conversation

PrasadBabarendaGamage commented Mar 12, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nickerso left a comment

Choose a reason for hiding this comment

Uh oh!

PrasadBabarendaGamage commented Mar 27, 2017

Uh oh!

hsorby left a comment

Choose a reason for hiding this comment

Uh oh!

PrasadBabarendaGamage commented Mar 30, 2017

Uh oh!

PrasadBabarendaGamage commented Mar 30, 2017

Uh oh!

hsorby commented Mar 30, 2017

Uh oh!

chrispbradley commented Mar 30, 2017

Uh oh!

rchristie commented Mar 30, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rchristie Apr 4, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rchristie Apr 4, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

PrasadBabarendaGamage commented Mar 12, 2017 •

edited

Loading

rchristie Apr 4, 2017 •

edited

Loading

rchristie Apr 4, 2017 •

edited

Loading