First draft of ODK Documentation Revamp

docs/AddTermToImport.md

@@ -1,13 +1 @@
-**NOTE** This documentation is incomplete, for now you may be better consulting the [GO Editor Docs](http://wiki.geneontology.org/index.php/Ontology_Editing_Guide)
-
-### Adding Terms to the Import Files
-
-Terms are imported to GO from other ontologies, but not all terms from external ontologies are imported. Occasionally, you will find that a valid identifier exists in an external ontology, but the identifier is not available in Protege because that term is not yet imported. To import a term from an external ontology:
-
-1.	Navigate to the imports folder on GitHub, located at [https://github.com/geneontology/go-ontology/tree/master/src/ontology/imports](https://github.com/geneontology/go-ontology/tree/master/src/ontology/imports).
-2.	Look in the list of ontologies for the ontology that contains the term you wish to import.
-3.	Identify the ```ontology_terms.txt``` file for the target ontology. For example, for the addition of a new taxon, the file can be found at [https://github.com/geneontology/go-ontology/blob/master/src/ontology/imports/ncbitaxon_terms.txt](https://github.com/geneontology/go-ontology/blob/master/src/ontology/imports/ncbitaxon_terms.txt).
-4.	Click on the icon of a pencil in the upper right corner of the window to edit the file.
-5.	Add the new term on the next available line at the bottom of the file.
-6.	Click preview changes.
-7.	You can now either commit the file directly to master or create a branch and a pull request as described before.
+See [https://oboacademy.github.io/obook/howto/update-import/](https://oboacademy.github.io/obook/howto/update-import/)

docs/CreatingRepo.md

@@ -1 +1 @@
-Please refer to https://oboacademy.github.io/obook/howto/odk-create-repo/
+Please refer to https://oboacademy.github.io/obook/tutorial/setting-up-project-odk/

docs/DailyWorkflow.md

@@ -1,130 +1 @@
-**NOTE** This documentation is incomplete, for now you may be better consulting the [GO Editor Docs](http://wiki.geneontology.org/index.php/Ontology_Editing_Guide)
-
-# Daily Workflow
-
-## Updating the local copy of the ontology with 'git pull'
-
-1. Navigate to the ontology directory of go-ontology:  ```cd repos/MY-ONTOLOGY/src/ontology```.
-
-2. If the terminal window is not configured to display the branch name, type: ```git status```. You will see: 
-
-       On branch [master] [or the name of the branch you are on]
-       Your branch is up-to-date with 'origin/master'.
-
-3. If you’re not in the master branch, type: ```git checkout master```.
-
-4. From the master branch, type: ```git pull```. This will update your master branch, and all working branches, with the files that are most current on GitHub, bringing in and merging any changes that were made since you last pulled the repository using the command ```git pull```. You will see something like this:
-
-```
-~/repos/MY-ONTOLOGY(master) $ git pull
-remote: Counting objects: 26, done.
-remote: Compressing objects: 100% (26/26), done.
-remote: Total 26 (delta 12), reused 0 (delta 0), pack-reused 0
-Unpacking objects: 100% (26/26), done.
-From https://github.com/geneontology/go-ontology
-   580c01d..7225e89  master 	-> origin/master
- * [new branch]  	issue#13029 -> origin/issue#13029
-Updating 580c01d..7225e89
-Fast-forward
- src/ontology/go-edit.obo | 39 ++++++++++++++++++++++++---------------
- 1 file changed, 24 insertions(+), 15 deletions(-)
-~/repos/MY-ONTOLOGY(master) $
-```
-
-## Creating a New Working Branch with 'git checkout'
-
-1. When starting to work on a ticket, you should create a new branch of the repository to edit the ontology file.
-
-2. **Make sure you are on the master branch before creating a new branch**. If the terminal window is not configured to display the branch name, type: ```git status``` to check which is the active branch. If necessary, go to master by typing ```git checkout master```.  
-
-3. To create a new branch, type:  ```git checkout -b issue-NNNNN``` in the terminal window. For **naming branches**, we recommend using the string 'issue-' followed by the issue number. For instance, for this issue in the tracker: https://github.com/geneontology/go-ontology/issues/13390, you would create this branch: ```git checkout -b issue-13390```. Typing this command will automatically put you in the new branch. You will see this message in your terminal window: 
-
-      ```
-      ~/repos/MY-ONTOLOGY/src/ontology(master) $ git checkout -b issue-13390
-      Switched to a new branch 'issue-13390'
-      ~/repos/MY-ONTOLOGY/src/ontology(issue-13390) $
-      ```
-
-
-## Continuing work on an existing Working Branch 
-1. If you are continuing to do work on an existing branch, in addition to updating master, go to your branch by typing ```git checkout [branch name]```. Note that you can view the existing local branches by typing ```git branch -l```.
-
-2. **OPTIONAL**: To update the working branch with respect to the current version of the ontology, type ```git pull origin master ```.
-This step is optional because it is not necessary to work on the current version of the ontology; all changes will be synchronized when git merge is performed.
-
-## Loading, navigating and saving the Ontology in Protégé 
-
-1. Before launching Protégé, make sure you are in the correct branch. To check the active branch, type ```git status```.  
-
-2. Click on the 'File' pulldown. Open the file: go-edit.obo. The first time, you will have to navigate to ```repos/MY-ONTOLOGY/src/ontology```. Once you have worked on the file, it will show up in the menu under 'Open'/'Recent'.
-
-3. Click on the 'Classes' tab.
-
-4. Searching: Use the search box on the upper right to search for a term in the ontology. Wait for autocomplete to work in the pop-up window.
-
-5. Viewing a term: Double-click on the term. This will reveal the term in the 'Class hierarchy' window after a few seconds.
-
-6. Launching the reasoner: To see the term in the 'Class hierarchy' (inferred) window, you will need to run the 'ELK reasoner'. 'Reasoner' > select ELK 0.4.3, then click 'Start reasoner'. Close the various pop-up warnings about the ELK reasoner. You will now see the terms in the inferred hierarchy.
-
-7. After modification of the ontology, synchronize the reasoner. Go to menu: 'Reasoner' > ' Synchronize reasoner'. 
-   - **NOTE**: The only changes that the reasoner will detect are those impacting the ontology structure: changes in equivalence axioms, subclasses, merges, obsoletions, new terms. 
-   - **TIP**: When adding new relations/axioms, 'Synchronize' the reasoner. When deleting relations/axioms, it is more reliable to 'Stop' and 'Start' the reasoner again. 
-
-8. Use File > Save to save your changes. 
-
-<a name="commmit"></a>
-## Committing, pushing and merging your changes to the repository
-
-1. **Review**: Changes made to the ontology can be viewed by typing ```git diff``` in the terminal window. If there are changes that have already been committed, the changes in the active branch relative to master can be viewed by typing  ```git diff master```. 
-
-2. **Commit**: Changes can be committed by typing: ```git commit -m ‘Meaningful message Fixes #ticketnumber’ go-edit.obo```. 
-
-      For example: 
-
-          git commit -m ‘hepatic stellate cell migration and contraction and regulation terms. Fixes #13390’ go-edit.obo 
-
-	This will save the changes to the go-edit.obo file. The terminal window will show something like: 
-
-        ~/repos/MY-ONTOLOGY/src/ontology(issue-13390) $ git commit -m 'Added hepatic stellate cell migration and contraction and regulation terms. Fixes #13390' go-edit.obo
-        [issue-13390 dec9df0] Added hepatic stellate cell migration and contraction and regulation terms. Fixes #13390
-        1 file changed, 79 insertions(+)
-        ~/repos/MY-ONTOLOGY/src/ontology(issue-13390) $
-
-   - **NOTE**: The word 'fixes' is a magic word in GitHub; when used in combination with the ticket number, it will automatically close the ticket. In the above example, when the file is merged in GitHub, it will close issue number 13390. Learn more on this [GitHub Help Documentation page about 'Closing issues via commit messages'](https://help.github.com/articles/closing-issues-via-commit-messages/).
-   - 'Fixes' is case-insensitive. 
-   - If you don't want to close the ticket, just refer to the ticket # without the word 'Fixes'. The commit will be associated with the correct ticket but the ticket will remain open. 
-    - **NOTE**: It is also possible to type a longer message than allowed when using the '-m' argument; to do this, skip the -m, and a vi window (on mac) will open in which an unlimited description may be typed. 
-   - **TIP**: Git needs to know who is committing changes to the repository, so the first time you commit, you may see the following message: 
-
-	     Committer: Kimberly Van Auken <[email protected]>
-            Your name and email address were configured automatically based on your username and hostname. Please check that they are accurate.
-   - See [Configuration instructions](http://ontology-development-kit.readthedocs.io/en/latest/index.html#configuration) to specify your name and email address. 
-
-3. **Push**: To incorporate the changes into the remote repository, type: ```git push origin mynewbranch```. 
-
-      Example: 
-
-        git push origin issue-13390 
-
-   - **TIP**: Once you have pushed your changes to the repository, they are available for everyone to see, so at this stage you can ask for feedback.    
-
-4. **Pull** 
-   1. In your browser, return to the [GO Ontology repository](https://github.com/geneontology/go-ontology) on GitHub.
-   2. Navigate to the tab labeled as 'Code' ```geneontology/go-ontology/code```. You will see your commit listed at the top of the page in a light yellow box. If you don’t see it, click on the 'Branches' link to reveal it in the list, and click on it. 
-   3. Click the green button 'Compare & pull request' on the right.
-   4. You may now add comments and ask a colleague to review your pull request. If you want to have the ticket reviewed before closing it, you can select a reviewer for the ticket before you make the pull request by clicking on the 'Reviewers' list and entering a GitHub identifier (e.g. @superuser1). The reviewer will be notified when the pull request is submitted.  Since the Pull Request is also a GitHub issue, the reviewer’s comments will show up in the dialog tab of the pull request, similarly to any other issue filed on the tracker.
-   5. The diff for your file is at the bottom of the page. Examine it as a sanity check. 
-   6. Click on the green box 'Pull request' to generate a pull request.   
-   7. Wait for the Travis checks to complete (this can take a few minutes). If the Travis checks failed, go back to your working copy and correct the reported errrors.   
-
-5. **Merge** If the Travis checks are succesful and **if you are done working on that branch**, merge the pull request. Confirming the merge will close the ticket if you have used the word 'fixes' in your commit comment. 
- **NOTE**: Merge the branches only when the work is completed. If there is related work to be done as a follow up to the original request, create a new GitHub ticket and start the process from the beginning. 
-
-6. **Delete** your branch on the repository using the button on the right of the successful merge message. 
-
-7. You may also delete the working branch on your local copy. Note that this step is optional.  However, if you wish to delete branches on your local machine, in your terminal window: 
-   1. Go back to the master branch by typing ```git checkout master```.     
-   2. Update your local copy of the repository by typing  ```git pull origin master``` 
-   3. Delete the branch by typing ```git branch -d workingbranchname```. 
-      Example:   ```git branch -d issue-13390```
-
+See [https://oboacademy.github.io/obook/tutorial/managing-ontology-project/](https://oboacademy.github.io/obook/tutorial/managing-ontology-project/).

docs/InitialSetup.md

@@ -1,58 +1 @@
-
-# Initial Setup for Ontology Developers
-
-## Installing Protege
-
-1. Follow the instructions on the GO wiki page: [http://wiki.geneontology.org/index.php/Protege_setup_for_GO_Eds](http://wiki.geneontology.org/index.php/Protege_setup_for_GO_Eds)
-
-2. _Need to add more here about the different Views and Tabs needed for working._
-
-
-## ID Ranges
-
-1. Curators and projects are assigned specific ID ranges within the prefix for your ontology. See the README-editors.md for your ontology
-
-2. An example: [go-idranges.owl](https://github.com/geneontology/go-ontology/blob/master/src/ontology/go-idranges.owl)
-
-3. __NOTE:__ You should only use IDs within your range.
-
-4. If you have only just set up this repository, modify the idranges file and add yourself or other editors. 
-
-
-## Setting ID ranges in Protege
-
-1. Once you have your assigned ID range, you need to configure Protege so that your ID range is recorded in the Preferences menu.  Protege does not read the idranges file.
-
-2. In the Protege menu, select Preferences.
-
-3. In the resulting pop-up window, click on the New Entities tab and set the values as follows.
-
-4. In the Entity IRI box:
-
-    __Start with:__ Specified IRI: [http://purl.obolibrary.org/obo](http://purl.obolibrary.org/obo)
-
-    __Followed by:__ ```/```
-
-    __End with:__ ```Auto-generated ID```
-
-5. In the Entity Label section:
-
-    __Same as label renderer:__ IRI: [http://www.w3.org/2000/01/rdf-schema#label](http://www.w3.org/2000/01/rdf-schema#label)
-
-6.  In the Auto-generated ID section:
-
-    * Numeric
-
-    * Prefix `GO_`
-
-    * Suffix: _leave this blank_
-
-    * Digit Count `7`
-
-    * __Start:__ see [go-idranges.owl](https://github.com/geneontology/go-ontology/blob/master/src/ontology/go-idranges.owl). Only paste the number after the ```GO:``` prefix.  Also, note that when you paste in your GO ID range, the number will automatically be converted to a standard number, e.g. pasting 0110001 will be converted to 110,001.)
-
-    * __End:__ see [go-idranges.owl](https://github.com/geneontology/go-ontology/blob/master/src/ontology/go-idranges.owl)
-
-    * Remember last ID between Protege sessions: ALWAYS CHECK THIS
-
-    (__Note:__ You want the ID to be remembered to prevent clashes when working in parallel on branches.)
+See [https://oboacademy.github.io/obook/pathways/ontology-curator-go-style/]