diff --git a/docs/AddTermToImport.md b/docs/AddTermToImport.md index 0d37068e..b963f521 100644 --- a/docs/AddTermToImport.md +++ b/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/) \ No newline at end of file diff --git a/docs/Configs.md b/docs/Configs.md deleted file mode 100644 index fbd9bc94..00000000 --- a/docs/Configs.md +++ /dev/null @@ -1,39 +0,0 @@ -**NOTE** This documentation is incomplete, for now you may be better consulting the [http://wiki.geneontology.org/index.php/Protege_setup_for_GO_Eds](GO Editor Docs] - -# Configuration - -## Configuring New Entities Metadata - -1. In the Protege menu, select Preferences. - -2. Click on: Annotate new entities with creator (user) - -3. Creator property: Add [http://www.geneontology.org/formats/oboInOwl#created_by](http://geneontology.org/formats/oboInOwl#created_by) - -4. Creator value: Use user name - -5. Check: Annotate new entities with creation date and time. - -6. Date property: Add [http://www.geneontology.org/formats/oboInOwl#creation_date](http://geneontology.org/formats/oboInOwl#creation_date) - -7. Check: ISO-8601 - - -## Configuring User details - -Select 'User name', and use the supplied user name; that is, your GOC identity. - -#### Identifying the user for commits - -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 - Your name and email address were configured automatically based on your username and hostname. Please check that they are accurate. - -You can suppress this message by setting your name and email explicitly: - -1. Type ```git config --global user.name "Your Name"``` - -2. Type ```git config --global user.email you@example.com```. - -3. You can then fix the identity used for this commit by typing: ```git commit --amend --reset-author```. diff --git a/docs/CreatingRepo.md b/docs/CreatingRepo.md index 20c7d3dc..ec6e51a1 100644 --- a/docs/CreatingRepo.md +++ b/docs/CreatingRepo.md @@ -1 +1 @@ -Please refer to https://oboacademy.github.io/obook/howto/odk-create-repo/ \ No newline at end of file +Please refer to [https://oboacademy.github.io/obook/tutorial/setting-up-project-odk/](https://oboacademy.github.io/obook/tutorial/setting-up-project-odk/) \ No newline at end of file diff --git a/docs/DailyWorkflow.md b/docs/DailyWorkflow.md index da7a2b78..f8be56cb 100644 --- a/docs/DailyWorkflow.md +++ b/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. - - -## 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 - 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/). \ No newline at end of file diff --git a/docs/InitialSetup.md b/docs/InitialSetup.md index d8687b0c..554e52fb 100644 --- a/docs/InitialSetup.md +++ b/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/](https://oboacademy.github.io/obook/pathways/ontology-curator-go-style/) \ No newline at end of file diff --git a/docs/Installgit.md b/docs/Installgit.md deleted file mode 100644 index 6a0b9341..00000000 --- a/docs/Installgit.md +++ /dev/null @@ -1,48 +0,0 @@ -**NOTE** This documentation is incomplete, for now you may be better consulting the [http://wiki.geneontology.org/index.php/Installing_and_Using_git](GO Editor Docs] - -# Installing and Using git - -## Installing git - -1. In order to locally edit the ontology and push changes back to the GitHub repository, you will need to have git installed on your machine. - -2. To check if you already have git installed, or to see what version of git you have, type either of these commands in your terminal: -```which git``` or ```git --version```. - -3. To install git, follow instructions here: [https://git-scm.com/](https://git-scm.com/) - - __Note for MacOSX users:__ it is advised to install Xcode tools. - - -## Cloning the go-ontology repository from GitHub - -1. Create a directory called ```repos``` on your local machine using this command: ```mkdir repos```. - -2. Then paste this command into your terminal: ```git clone https://github.com/geneontology/go-ontology.git```. - - Example result: - - Cloning into 'go-ontology'... - remote: Counting objects: 2541, done. - remote: Compressing objects: 100% (100/100), done. - remote: Total 2541 (delta 52), reused 0 (delta 0), pack-reused 2440 - Receiving objects: 100% (2541/2541), 21.19 MiB | 5.22 MiB/s, done. - Resolving deltas: 100% (1532/1532), done. - - -## Editing the .profile (or .bashrc) file to indicate the branch you are working on - -It can be very helpful to know what branch you are working in on your terminal window. You can set this up to display by adding the following information to your .profile file (found by typing ls -a): - - export GO_REPO=~/repos/MY-ONTOLOGY - . $GO_REPO/src/util/git-completion.bash - parse_git_branch() { - git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/(\1)/' - } - PS1="\w\$(parse_git_branch) $ " - export PATH=$PATH:$HOME/bin/ - - Note the last line is not relevant to git, but we do this now for later on when we want to run tools like robot. - - - diff --git a/docs/License.md b/docs/License.md index f485c3fc..6d41cb82 100644 --- a/docs/License.md +++ b/docs/License.md @@ -1,97 +1 @@ -# Formatting your ontology annotations correctly - -The new OBO Foundry guidelines encourage the annotation of ontologies with an appropriately formatted description, title and license. Here are some examples that can be used as a guide to implement those in your ontology. - -## RDF/XML Example: - -``` - - - - An integrated and fictional ontology for the description of abnormal tomato phenotypes. - Tomato Phenotype Ontology (TPO) - - - - - - -``` - -## Functional Syntax Example: - -``` -Prefix(:=) -Prefix(owl:=) -Prefix(rdf:=) -Prefix(xml:=) -Prefix(xsd:=) -Prefix(rdfs:=) - - -Ontology( -Annotation( "An integrated and fictional ontology for the description of abnormal tomato phenotypes."^^xsd:string) -Annotation( "Tomato Phenotype Ontology (TPO)"^^xsd:string) -Annotation( ) - -) -``` - -## OWL/XML Example: - -``` - - - - - - - - - - - An integrated and fictional ontology for the description of abnormal tomato phenotypes. - - - - Tomato Phenotype Ontology (TPO) - - - - https://creativecommons.org/licenses/by/3.0/ - - - - - - - - - - - -``` - -## OBO Example: - -``` -format-version: 1.2 -ontology: license -property_value: http://purl.org/dc/elements/1.1/description "An integrated and fictional ontology for the description of abnormal tomato phenotypes." xsd:string -property_value: http://purl.org/dc/elements/1.1/title "Tomato Phenotype Ontology (TPO)" xsd:string -property_value: http://purl.org/dc/terms/license https://creativecommons.org/licenses/by/3.0/ -``` +Refer to [https://oboacademy.github.io/obook/reference/formatting-license/](https://oboacademy.github.io/obook/reference/formatting-license/). \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 010ea3cf..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = ontology-development-kit -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/ReleaseArtefacts.md b/docs/ReleaseArtefacts.md index a504f6ad..22498c6e 100644 --- a/docs/ReleaseArtefacts.md +++ b/docs/ReleaseArtefacts.md @@ -1,121 +1 @@ -# Release artefacts - -We made a first stab add defining release artefacts that should cover all use cases community-wide. We need to (1) agree they are all that is needed and (2) they are defined correctly in terms of ROBOT commands. This functionality replaces what was previously done using OORT. - -## Terminology: -The **source ontology** is the ontology we are talking about. A **release artefact** is a version of the ontology modified in some specific way, intended for public use. An **import** is a module of an external ontology which contains all the axioms necessary for the source ontology. A **component** is a file containing axioms that belong to the source ontology (but are for one reason or another, like definitions.owl, managed in a separate file). An axiom is said to be **foreign** if it 'belongs' to a different ontology, and **native** if it belongs to the source ontology. For example, the source ontology might have, for one reason or another, been physically asserted (rather than imported) the axiom TransitiveObjectProperty(BFO:000005). If the source ontology does not 'own' the BFO namespace, this axiom will be considered foreign. - -There are currently 6 release defined in the ODK: - -- base (required) -- full (required) -- non-classified (optional) -- simple (optional) -- basic (optional) -- simple-non-classified (optional, transient) - -We discuss all of them here in detail. - -# Release artefact 1: base (required) -The base file contains all and only **native** axioms. No further manipulation is performed, in particular no reasoning, redundancy stripping or relaxation. This release artefact is going to be the new backbone of the OBO strategy to combat incompatible imports and consequent lack of interoperability. (Detailed discussions elsewhere, @balhoff has documentation). Every OBO ontology will contain a mandatory base release (should be in the official OBO recommendations as well). - -The ROBOT command generating the base artefact: -$(SRC): source ontology -$(OTHER_SRC): set of component ontologies -``` -$(ONT)-base.owl: $(SRC) $(OTHER_SRC) - $(ROBOT) remove --input $< --select imports --trim false \ - merge $(patsubst %, -i %, $(OTHER_SRC)) \ - annotate --ontology-iri $(ONTBASE)/$@ --version-iri $(ONTBASE)/releases/$(TODAY)/$@ --output $@ -``` -# Release artefact 2: full (required) -The full release artefact contains all logical axioms, including inferred subsumptions. Redundancy stripping (i.e. redundant subclass of axioms) and typical relaxation operations are performed. All imports and components are merged into the full release artefact to ensure easy version management. The full release represents most closely the actual ontology as it was intended at the time of release, including all its logical implications. Every OBO ontology will contain a mandatory full release. - -The ROBOT command generating the full artefact: -$(SRC): source ontology -$(OTHER_SRC): set of component ontologies - -``` -$(ONT)-full.owl: $(SRC) $(OTHER_SRC) - $(ROBOT) merge --input $< \ - reason --reasoner ELK \ - relax \ - reduce -r ELK \ - annotate --ontology-iri $(ONTBASE)/$@ --version-iri $(ONTBASE)/releases/$(TODAY)/$@ --output $@ -``` -# Release artefact 3: non-classified (optional) -The non-classified release artefact reflects the 'unmodified state' of the editors file at release time. No operations are performed that modify the axioms in any way, in particular no redundancy stripping. As opposed to the base artefact, both component and imported ontologies are merged into the non-classified release. - -The ROBOT command generating the full artefact: -$(SRC): source ontology -$(OTHER_SRC): set of component ontologies - -``` -$(ONT)-non-classified.owl: $(SRC) $(OTHER_SRC) - $(ROBOT) merge --input $< \ - annotate --ontology-iri $(ONTBASE)/$@ --version-iri $(ONTBASE)/releases/$(TODAY)/$@ --output $@ -``` - -# Release artefact 4: simple (optional) - -Many users want a release that can be treated as a simple existential graph of the terms defined in an ontology. This corresponds to the state of OBO ontologies before logical definitions and imports. For example, the only logical axioms in -simple release of CL will contain be of the form `CL1 subClassOf CL2` or `CL1 subClassOf R some CL3` where R is any objectProperty and CLn is a CL class. This role has be fulfilled by the -simple artefact, which up to now has been supported by OORT. - -To construct this, we first need to assert inferred classifications, relax equivalentClass axioms to sets of subClassOf axioms and then strip all axioms referencing foreign (imported) classes. As ontologies occasionally end up with forieign classes and axioms merged into the editors file, we achieve this will a filter based on obo-namespace. (e.g. finding all terms with iri matching http://purl.obolibrary.org/obo/CL_{\d}7). - -The ROBOT command generating the full artefact: -$(SRC): source ontology -$(OTHER_SRC): set of component ontologies -$(SIMPLESEED): all terms that 'belong' to the ontology - -``` -$(ROBOT) merge --input $< $(patsubst %, -i %, $(OTHER_SRC)) \ - reason --reasoner {{ project.reasoner }} --equivalent-classes-allowed {{ project.allow_equivalents }} \ - relax \ - remove --axioms equivalent \ - relax \ - filter --term-file $(SIMPLESEED) --select "annotations ontology anonymous self" --trim true --signature true \ - reduce -r {{ project.reasoner }} \ - annotate --ontology-iri $(ONTBASE)/$@ --version-iri $(ONTBASE)/releases/$(TODAY)/$@ --output $@.tmp.owl && mv $@.tmp.owl $@ -``` -NOTES: This requires $(ONTOLOGYTERMS) to include all ObjectProperties usesd. `--select parents` is required for logical axioms to be retained, but results in a few upper-level classes bleeding through. We hope this will be fixed by further improvments to Monarch. - - -# Release artefact 5: basic - -Some legacy users (e.g. MGI) require an OBO DAG version of -simple. OBO files derived from OWL are not guarenteed to be acyclic, but acyclic graphs can be achieved using judicious filtering of relationships (simple existential restrictions) by objectProperty. The -basic release artefact has historically fulfilled this function as part of OORT driven ontology releases. The default -basic version corresponds to the -simple artefact with only 'part of' relationships (BFO:0000050), but others may be added where ontology editors judge these to be useful and safe to add without adding cycles. We generate by taking the simple release and filtering it - -The ROBOT command generating the full artefact: -$(SRC): source ontology -$(OTHER_SRC): set of component ontologies -$(KEEPRELATIONS): all relations that should be preserved. -$(SIMPLESEED): all terms that 'belong' to the ontology - -``` -$(ROBOT) merge --input $< $(patsubst %, -i %, $(OTHER_SRC)) \ - reason --reasoner {{ project.reasoner }} --equivalent-classes-allowed {{ project.allow_equivalents }} \ - relax \ - remove --axioms equivalent \ - remove --axioms disjoint \ - remove --term-file $(KEEPRELATIONS) --select complement --select object-properties --trim true \ - relax \ - filter --term-file $(SIMPLESEED) --select "annotations ontology anonymous self" --trim true --signature true \ - reduce -r {{ project.reasoner }} \ - annotate --ontology-iri $(ONTBASE)/$@ --version-iri $(ONTBASE)/releases/$(TODAY)/$@ --output $@.tmp.owl && mv $@.tmp.owl $@ -``` - -# Release artefact 6: simple-non-classified (optional) -This artefact caters to the very special and *hopefully transient* case of some ontologies that do not yet trust reasoning (MP, HP). The simple-non-classified artefact corresponds to the simple artefact, just without the reasoning step. - -$(SRC): source ontology -$(OTHER_SRC): set of component ontologies -$(ONTOLOGYTERMS): all terms that 'belong' to the ontology - -``` -$(ONT)-simple-non-classified.owl: $(SRC) $(OTHER_SRC) $(ONTOLOGYTERMS) - $(ROBOT) remove --input $< --select imports \ - merge $(patsubst %, -i %, $(OTHER_SRC)) \ - relax \ - reduce -r ELK \ - filter --term-file $(ONTOLOGYTERMS) --trim true \ - annotate --ontology-iri $(ONTBASE)/$@ --version-iri $(ONTBASE)/releases/$(TODAY)/$@ -``` \ No newline at end of file +Please refer to [https://oboacademy.github.io/obook/reference/release-artefacts/](https://oboacademy.github.io/obook/reference/release-artefacts/) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 509ecebf..00000000 --- a/docs/conf.py +++ /dev/null @@ -1,274 +0,0 @@ -# -*- coding: utf-8 -*- -# -# OBO Ontology documentation build configuration file, modeled after file created by -# sphinx-quickstart. Wednesday 2017-08-04. -# -# by MMT -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -import sys -import os -sys.path.append(os.path.abspath('exts')) - - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'markdowntransform', - 'alabaster', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -from recommonmark.parser import CommonMarkParser - -source_parsers = { - '.md': CommonMarkParser, -} -source_suffix = ['.rst', '.md'] - -# The encoding of source files. -# source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Ontology Development Kit' -copyright = u'2012, OBO Foundry' -author = u'OBO Foundry team' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.5' -# The full version, including alpha/beta/rc tags. -release = '0.5' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'ontology-development-kit' - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ('index', 'ontology-development-kit.tex', u'ontology-development-kit Documentation', - u'ontology-development-kit', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'ontology-development-kit', u'ontology-development-kit Documentation', - [u'ontology-development-kit'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'ontology-development-kit', u'ontology-development-kit Documentation', - u'ontology-development-kit', 'ontology-development-kit', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False diff --git a/docs/index.md b/docs/index.md index b8d8f0d3..c1938618 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1,30 @@ -# ODK Documentation +# The Ontology Development Kit (ODK) - Documentation + + + +Manage your ontology's life cycle with the Ontology Development Kit (ODK)! + +The ODK is +- a toolbox of various ontology related tools such as ROBOT, owltools, dosdp-tools and many more, bundled as a docker image +- a set of executable workflows for managing your ontology's continuous integration, quality control, releases and dynamic imports + +For more details, see + + * [2022 Paper](https://doi.org/10.1093/database/baac087) + * [2018 Article](https://douroucouli.wordpress.com/2018/08/06/new-version-of-ontology-development-kit-now-with-docker-support/) + * [ICBO Workshop Slides 2018](https://docs.google.com/presentation/d/1nIybviEEJiRKHO2rkBMZsQ0QjtsHyU01_-9beZqD_Z4/edit?usp=sharing) + * [ICBO Workshop Slides 2017](https://docs.google.com/presentation/d/1JPAaDl6Nitxet9NVqWI30eIygcerYAjdMIGmxbRtIn0/edit?usp=sharing) + +# Where to get help + +- _How-to guides_: + - How to [create your first repository](https://oboacademy.github.io/obook/tutorial/setting-up-project-odk/) with the ODK + - [ODK in 20 minutes](https://oboacademy.github.io/obook/tutorial/odk-tutorial-2/) + - [ODK adding custom QC checks](https://oboacademy.github.io/obook/tutorial/custom-qc/) + - How to [import large ontologies efficiently](https://oboacademy.github.io/obook/howto/deal-with-large-ontologies/) +- Reference: + - Learn about the [different kinds of release artefacts](https://oboacademy.github.io/obook/reference/release-artefacts/) + - Learn about the [ODK Project Configuration Schema](project-schema.md) for allowed parameters in your `[project]-odk.yaml` +- Community: + - If you have issues, file them on [our issue tracker](https://github.com/INCATools/ontology-development-kit/issues) + - We also have an active community on Slack; you can request access by making a ticket [here](https://github.com/INCATools/ontology-development-kit/issues) diff --git a/docs/schema-options.md b/docs/schema-options.md new file mode 100644 index 00000000..03e6002e --- /dev/null +++ b/docs/schema-options.md @@ -0,0 +1,9 @@ +# Breakdown of values for the ODK schema + +The auto-generated schema can be found [here](project-schema.md). + +This document provides additional explanations about options in the ODK schema. + +# Module types + +TBD \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 4ab7fe00..f5a010fc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,8 +20,12 @@ extra_javascript: - https://unpkg.com/mermaid@8.5.1/dist/mermaid.min.js nav: - - Frontpage: index.md - - ODK Configuration Options: project-schema.md + - Home: index.md + - ODK User Docs: + - ODK Schema: project-schema.md + - ODK Schema Options: schema-options.md + - Using the Development Snapshot: ODKDevelopmentSnapshot.md + - Frequently used ODK commands: FrequentlyUsedODKCommands.md repo_url: https://github.com/INCATools/ontology-development-kit/ site_url: https://incatools.github.io/ontology-development-kit/