Skip to content

Commit

Permalink
Fall cleaning (OBOFoundry#2122)
Browse files Browse the repository at this point in the history 
* Begin fall cleaning

* Add additional registry hints for products

* Cleanup python validation

* Consolidate logos folder into images folder

* Clean up README text

* More README cleanup

* Move related projects

* Delete remaining legacy

* Delete browse.html

* Update resources.md

* Update validate-metadata.py

* Simplify docs

* Update how-do-i-edit-metadata.md

* Update README.md

Co-authored-by: Nico Matentzoglu <[email protected]>

* Update README-sitedev.md

* Update README.md

* Update resources.md

Co-authored-by: Nico Matentzoglu <[email protected]>
  • Loading branch information
@cthoyt @matentzn
cthoyt and matentzn authored Oct 9, 2022
1 parent 407276d commit 9474e2b
Show file tree
Hide file tree
Showing 17 changed files with 58 additions and 1,106 deletions.
46 changes: 11 additions & 35 deletions README-sitedev.md
View file
Original file line number Diff line number Diff line change
@@ -1,41 +1,21 @@
This documentation is for developers of this prototype OBO Foundry site.
# Site Development

Note this document is in markdown and is best viewed on GitHub.
This documentation is for developers of this prototype OBO Foundry site.

## Getting Started

You will first need jekyll, which can be installed by the ruby [gem](https://rubygems.org/):

gem install jekyll

After checking out the code from GitHub, you can start a local server:

jekyll serve

(this must always be done from the top level)

Then view http://127.0.0.1:4000

You can make changes locally (you will need to start jekyll again - no
hot fixes).

If you commit and push, your change will be visible within a few
minutes on: http://obofoundry.github.io

If this site becomes official we may want to institute policies for
the site: e.g. major new changes happen on forks/branches, with a
voting policy for merging these in.

### Serving with Docker

Because Jekyll can be difficult to install, Docker provides an
alternative for running the `serve` command:
alternative for running the `serve` command, then open http://localhost:4000:

```shell
$ export JEKYLL_VERSION=3.5
$ docker run --rm --volume="$PWD:/srv/jekyll" -p 4000:4000 -it jekyll/jekyll:$JEKYLL_VERSION jekyll serve
$ docker run --rm --volume="$PWD:/srv/jekyll" -p 4000:4000 -it jekyll/jekyll:3.5 jekyll serve
```

You can make changes locally and the Docker image will automatically update.
When you're ready, you can commit to a new branch and send a pull request.
After it's accepted, it will be automatically built and deployed to
http://obofoundry.github.io in a few minutes.

## Details

The setup is fairly standard for Jekyll. We use Jekyll bootstrap
Expand Down Expand Up @@ -141,13 +121,9 @@ We could in theory easily manage our principles here. E.g. one .md
file per principle. I personally think this much better than the
current wiki, but other opinions welcome.

### Bootstrap Conventions

We use bootstrap 3, so far no themes.

### Code quality

1. Install the Node Package Manager (NPM) following [these instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
2. Install the [node package exector (`npx`)](https://www.npmjs.com/package/npx) with NPM using `npm install npx`
2. Install [`prettier`](https://prettier.io) with NPM using `npm install prettier`
3. Run `prettier` from the root of the repository with `npx prettier --write .`
3. Install [`prettier`](https://prettier.io) with NPM using `npm install prettier`
4. Run `prettier` from the root of the repository with `npx prettier --write .`
132 changes: 18 additions & 114 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,17 @@
[![Build Status](https://travis-ci.org/OBOFoundry/OBOFoundry.github.io.svg?branch=master)](https://travis-ci.org/OBOFoundry/OBOFoundry.github.io)
# OBO Foundry Registry and Website

## OBO Foundry Registry and Website
This is the registry and website for the OBO Foundry. It is deployed with GitHub
Pages and Jekyll to https://obofoundry.github.io and is then mapped to
https://obofoundry.org.

### What is this?
For most questions, see the main site FAQ at https://obofoundry.org/faq/.
For details on site development, please see [README-sitedev.md](README-sitedev.md)

This is the registry and website for the OBO Foundry.

It uses GitHub pages and can be visible here: http://obofoundry.github.io/

We map http://obofoundry.org to this address.

### How does it work?

The source can be found on https://github.com/OBOFoundry/OBOFoundry.github.io

It uses GitHub Pages/[Jekyll](https://en.wikipedia.org/wiki/Jekyll_%28software%29),
a popular static site generator.

GitHub pages [are integrated with
github](https://help.github.com/articles/using-jekyll-with-pages/)
which means that the entire site can be seen on
http://obofoundry.github.io (we don't run a dedicated webserver)

For more details see: [README-sitedev.md](README-sitedev.md)
## Contributing

### I have some comments

You can use the [issue
tracker](https://github.com/OBOFoundry/OBOFoundry.github.io/issues)
but you may want to hold off til things are more stable
You can use the [issue tracker](https://github.com/OBOFoundry/OBOFoundry.github.io/issues)

### I want to contribute

Expand All @@ -49,7 +32,6 @@ See [CONTRIBUTING.md](CONTRIBUTING.md)
* [ontology/uberon.md](ontology/uberon.md)
* ...
* [Makefile](Makefile) `<-- For compiling derived artefacts and running tests`
* [.travis.yml](.travis.yml) `<-- continuous integration config`
* [_posts/](_posts) `<-- Blog posts/news`
* [_layouts/](_layouts) `<-- Jekyll layouts`
* [_includes/](_includes) `<-- Jekyll includes`
Expand All @@ -67,14 +49,14 @@ For example:
* [ontology/uberon.md](ontology/uberon.md)
* [ontology/bfo.md](ontology/bfo.md)

Each md file consists of
Each `*.md` file consists of

* YAML metadata
* Markdown text to be shown on the page for that ontology

For example:

```
```markdown
---
layout: ontology_detail
id: aeo
Expand All @@ -95,46 +77,25 @@ AEO is an ontology of anatomical structures that expands CARO, the Common Anatom
The [aeo page](http://obofoundry.github.io/ontology/aeo.html) shows the structured info on the right and the formatted text on the right. (THIS IS A BAD EXAMPLE IT HAS NO FORMATTING)

The YAML data is strictly vetted by OBO team. The Makefile takes care
of syntactic validation (the travis job runs `make test`). The OBO
of syntactic validation (the GitHub Actions runs `make test`). The OBO
team ensures the content is correct, up to date and accurate.

You can put any HTML or Markdown in the lower section - customize each ontology page!

Note that each md file is the primary source for the metadata for each
ontology. It may seem odd to mix the markdown in with the yaml, but in
practice this works well and is easy to mainpulate using the python
practice this works well and is easy to manipulate using the python
script in the util/ directory.

The one piece of visual info in the md is the `layout` field, which is necessary for Jekyll.


### Generation of downstream artefacts

OBO admins should periodically

git pull
make
jekyll server
## open 127.0.0.1:4000 in a web browser and spot-check changes
git commit -m 'regenerated derived files' -a
git push origin master

See the `Makefile` for details. This will have the effect of
regenerating the main ontologies yaml (used by external consumers such
as OLS, as well as the central OBO library build), as well as the
GitHub pages `_config.yml` file. This last step is necessary to update
the front page.

_Note_: This process works using Ruby 2.6.6 and Jekyll 4.2.0. We tried using Ruby 3.0, but the setup failed for various reasons (missing libraries, obsolete/removed methods). If you are using Mac OS, we recommend using [rvm](https://rvm.io/rvm/install) to install the Ruby version.


#### RDF

The yaml is all "YAML-LD" and can compile down to RDF/OWL using a generic translator (eg JENA) plus our context file.

### Community Contributions

Note that general OBO users are free to edit via the github web
Note that general OBO users are free to edit via the GitHub web
interface and make a pull request. They can update their own entries,
but they are also welcome to suggest changes elsewhere.

Expand All @@ -145,10 +106,10 @@ For example:
* [view ontology/uberon.md](https://github.com/OBOFoundry/OBOFoundry.github.io/blob/master/ontology/uberon.md)
* [edit ontology/uberon.md](https://github.com/OBOFoundry/OBOFoundry.github.io/edit/master/ontology/uberon.md)

Note that joe randoms cannot just come in and update things. Anyone with a github ID can make [pull request](https://help.github.com/articles/using-pull-requests/)
Note that joe randoms cannot just come in and update things. Anyone with a GitHub account can make [pull request](https://help.github.com/articles/using-pull-requests/)
(aka PR). It is up to the OBO team whether the PR may be merged or rejected.

Note that if you make a syntax error whilst editing, then the travis
Note that if you make a syntax error whilst editing, then the GitHub Actions
check will fail. Your PR will have a big red X next to it, in which
case the OBO team will not merge your PR. Don't worry, all you have to
do is make further edits to fix the syntax error.
Expand All @@ -174,7 +135,7 @@ Depending on the build configuration, this may also make additional files. See f

* http://berkeleybop.org/ontologies/uberon/

A http://berkeleybop.org/ontologies/ URL should never be handed out directly. This service exists so that:
A http://berkeleybop.org/ontologies/ URL should never be handed out directly. This service exists so that:

* Un PURL-registered ontologies will have a fall-through
* Registered PURL ontologies that do not want to take charge of either OBO or OWL generation will have a place to 302-redirect to
Expand All @@ -185,63 +146,6 @@ This job will fail if ontologies marked as `infallible` fail. To debug, the full

(Look for the text "should not fail")

## Adding news

Simply add a post to the [_posts/](_posts/) directory - copy an exiting one if you like

Posts can also be edited via the GH web interface, all posts are here:

https://github.com/OBOFoundry/OBOFoundry.github.io/tree/master/_posts

## Instructions for WebSite developers

Consult online Jekyll docs for details. Basically you just do

gem install jekyll

(I am currently using Jekyll 4.2.0 on Ruby 2.6.6; I tried using Ruby 3.0, but the setup failed for various reasons (missing libraries, obsolete/removed methods). If you are using Mac OS, I recommend using [rvm](https://rvm.io/rvm/install) to install the Ruby version.)

You can run a local test install from the top level directory

jekyll serve

Then open http://127.0.0.1:4000

Every commit is visible within a few minutes on: http://obofoundry.github.io

You may want to work on a branch to avoid disrupting the live
site. Exact procedures for accepting changes back into master have yet
to be determined. See [CONTRIBUTING.md](CONTRIBUTING.md) for a draft.

The setup is fairly standard for Jekyll. We use Jekyll bootstrap
(bootstrap 3). We try and keep things minimal so that the site will
work on github. Even if you have no knowledge of Jekyll, it is fairly
easy to introspect what is going on if you have done much CMS work or
web development.

Basics:

* source can be markdown or html
* Different styles of pages go in _layouts
* ...

## Site FAQ

See also the main FAQ on the website: this FAQ is for OBO internal people

### It's missing feature X from the old site

File an issue! Or better yet, make a change on a fork and make a PR!

### Shouldn't we pull project data from the ontologies themselves?

We should definitely have some mechanism for syncing these or allowing
this option. However, for the majority of ontologies for which I (cjm)
are de-facto administrating, the expertise and time to do this in OWL
is not there, and many groups prefer to have this centralized.





## Instructions for Website Development

See [README-sitedev.md](README-sitedev.md)
26 changes: 0 additions & 26 deletions _layouts/browse_layout.html
View file

This file was deleted.

41 changes: 0 additions & 41 deletions browse.html
View file

This file was deleted.

30 changes: 11 additions & 19 deletions faq/how-do-i-edit-metadata.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,32 +64,24 @@ A few key properties to be aware of:

### Freeform Markdown

The section after the second `---` controls what goes in the main panel on your ontology page. You should include at least a one paragarph description here. You are free to put more detail, and you can use a mixture of HTML and Markdown formatting. You can even put images in here.
The section after the second `---` controls what goes in the main panel on your ontology page. You should include at least a one paragraph description here. You are free to put more detail, and you can use a mixture of HTML and Markdown formatting. You can even put images in here. You should not put citations, funding statements, or other information that is possible to include in the structured data.

For example, here is the ENVO freeform markdown section
For example, here is the AMPHX freeform markdown section

```
EnvO is a community ontology for the concise, controlled description of environments.
<img src="/logos/envo.png"/>
Envo can be cited as:
Buttigieg, P. L., Morrison, N., Smith, B., Mungall, C. J., & Lewis, S. E. (2013). <b>The environment ontology: contextualising biological and biomedical entities</b>. <i>Journal of Biomedical Semantics, 4(1), 43</i>. <a href="http://www.dx.doi.org/10.1186/2041-1480-4-43">doi:10.1186/2041-1480-4-43</a>
```markdown
The Amphioxus Development and Anatomy Ontology (AMPHX) is to describe the anatomy and development of Amphioxus, also known as lancelet, member of the invertebrate subphylum Cephalochordata and the phylum Chordata. This ontology is intended to be used for description of gene expression in amphioxus (e.g. Insitus, RNA-seq). The ontology was created in the context of the European project [CORBEL](https://www.corbel-project.eu/home.html), and used in the database [MARIMBA](http://marimba.obs-vlfr.fr/home).
```

### Pull Request Pipeline

Any user can make propsed changes to any md file. These remain on
their fork until approved by OBO admins.

The workflow is:
Any user can make proposed changes to any `*.md` file. These remain on
their fork until approved by OBO admins. The workflow is:

1. An automated Travis job will run to validate your changes
2. An OBO administrator will evaluate your PR. If it failed the travis check, it will not be accepted
3. If the the OBO admin rejects it they will provide feedback in the comment form which you can use to make further edits
4. More likely, the change will be accepted by the OBO admin. They will click "merge" and the changes will be visible in a few seconds.
5. The OBO admin will also need to run a Make script to regenerate the main metadata file, so your changes may not be visible on the front table straight away
1. An automated GitHub Actions job will run to validate your changes
2. An OBO administrator will evaluate your PR. If it failed the checks, it will not be accepted
3. If the the OBO admin rejects it they will provide feedback in the comment form which you can use to make further edits
4. More likely, the change will be accepted by the OBO admin. They will click "squash and merge".
5. An automated GitHub Actions workflow will update the build artifacts and issue a new PR. An OBO admin can review and accept.

## Pull Request Tutorial

Expand Down
0 logos/envo.png → images/envo.png
View file
File renamed without changes
Loading

0 comments on commit 9474e2b

Please sign in to comment.