Skip to content

Commit

Permalink
Update markdown styling for all markdown files
Browse files Browse the repository at this point in the history 
Remove README under tests/.
  • Loading branch information
@CasperWA
CasperWA committed Sep 27, 2021
1 parent fe097ca commit 9599b9d
Show file tree
Hide file tree
Showing 11 changed files with 351 additions and 536 deletions.
22 changes: 10 additions & 12 deletions demo/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,16 @@
EMMO use cases
==============
This demo contains two use cases on how EMMO can be used to achieve
vertical and horizontal interpoerability, respectivily.
# EMMO use cases

> **WARNING**: This demonstration is still work in progress. Especially documentation is lacking.
This demo contains two use cases on how EMMO can be used to achieve vertical and horizontal interpoerability, respectivily.

!!! warning
This demonstration is still work in progress.
Especially documentation is lacking.

Content
-------
* [Vertical interoperability](vertical/README.md)
* [Horizontal interoperability](horizontal/README.md)
## Content

- [Vertical interoperability](vertical/README.md).
- [Horizontal interoperability](horizontal/README.md).

The user case - welding an aluminium plate to steel
===================================================
## The user case - welding an aluminium plate to steel

FIXME - add an overall description of the user case here...
<!-- FIXME - add an overall description of the user case here... -->
48 changes: 17 additions & 31 deletions demo/horizontal/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,53 +1,39 @@
EMMO use case for horizontal interoperability
=============================================
Horizontal interoperability is about interoperability between
different types of models and codes for a single material (i.e. one
use case, multiple models).
# EMMO use case for horizontal interoperability

The key here is to show how to map between EMMO (or an EMMO-based
ontology) and another ontology (possible EMMO-based). In this example
we use a data-driven approach based on a C-implementation of SOFT [1][2].
Horizontal interoperability is about interoperability between different types of models and codes for a single material (i.e., one use case, multiple models).

The key here is to show how to map between EMMO (or an EMMO-based ontology) and another ontology (possible EMMO-based).
<!-- markdownlint-disable-next-line MD033 -->
In this example we use a data-driven approach based on a C-implementation of SOFT<sup>[1],[2]</sup>.

This is done in four steps:

1. Generate metadata from the EMMO-based user case ontology.

Implemented in the script
[step1_generate_metadata.py](step1_generate_metadata.py).
Implemented in the script [step1_generate_metadata.py](step1_generate_metadata.py).

2. Define metadata for an application developed independently of EMMO.

In this case a metadata description of the ASE Atoms class [3] is
created in `atoms.json`.

Implemented in the script
[step2_define_metadata.py](step2_define_metadata.py).
In this case a metadata description of the ASE Atoms class [3] is created in `atoms.json`.

3. Instantiate the metadata defined defined in step 2 with an
atomistic structure interface structure.
Implemented in the script [step2_define_metadata.py](step2_define_metadata.py).

Implemented in the script
[step3_instantiate.py](step3_instantiate.py).
3. Instantiate the metadata defined defined in step 2 with an atomistic structure interface structure.

4. Map the atomistic interface structure from the application
representation to the common EMMO-based representation.
Implemented in the script [step3_instantiate.py](step3_instantiate.py).

Implemented in the script
[step4_map_instance.py](step4_map_instance.py).
4. Map the atomistic interface structure from the application representation to the common EMMO-based representation.

Essentially this demonstration shows how EMMO can be extended and how
external data can be mapped into our extended ontology (serving as a
common representational system).
Implemented in the script [step4_map_instance.py](step4_map_instance.py).

Essentially, this demonstration shows how EMMO can be extended and how external data can be mapped into our extended ontology (serving as a common representational system).

## Requirements for running the user case

Requirements for running the user case
--------------------------------------
In addition to emmo, this demo also requires:
- [dlite][1], a C-implementation of [SOFT][2] used for handling metadata
- [ASE][3], for reading atom structure from cif and visualisation


- [DLite][1], a C-implementation of [SOFT][2] used for handling metadata
- [ASE][3], for reading atom structure from cif and visualisation

[1]: https://github.com/jesper-friis/DLite
[2]: https://github.com/NanoSim/SOFT5
Expand Down
125 changes: 57 additions & 68 deletions examples/emmodoc/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,79 +1,68 @@
Generate documentation for EMMO
===============================
This directory contains the needed templates, introductory text and
figures for generating the full EMMO documentation using `ontodoc`.
Since the introduction is written in markdown, pandoc is required for
both pdf and html generation.
# Generate documentation for EMMO

For a standalone html documentation including all inferred relations,
enter this directory and run
This directory contains the needed templates, introductory text and figures for generating the full EMMO documentation using `ontodoc`.
Since the introduction is written in markdown, pandoc is required for both pdf and html generation.

ontodoc --template=emmo.md --format=html emmo-inferred emmo.html
For a standalone html documentation including all inferred relations, enter this directory and run:

Pandoc options may be adjusted with the files
[pandoc-args.yaml](pandoc-args.yaml) and
[pandoc-html-args.yaml](pandoc-html-args.yaml).
```console
ontodoc --template=emmo.md --format=html emmo-inferred emmo.html
```

Similarly, for generating pdf documentation, enter this directory and run
Pandoc options may be adjusted with the files [pandoc-args.yaml](pandoc-args.yaml) and [pandoc-html-args.yaml](pandoc-html-args.yaml).

ontodoc --template=emmo.md emmo-inferred emmo.pdf
Similarly, for generating pdf documentation, enter this directory and run:

By default, we have configured pandoc to use xelatex for better unicode
support. It is possible to change these settings in
[pandoc-options.yaml](pandoc-options.yaml) and
[pandoc-pdf-options.yaml](pandoc-pdf-options.yaml).
```console
ontodoc --template=emmo.md emmo-inferred emmo.pdf
```

By default, we have configured pandoc to use xelatex for better unicode support.
It is possible to change these settings in [pandoc-options.yaml](pandoc-options.yaml) and [pandoc-pdf-options.yaml](pandoc-pdf-options.yaml).

## Content of this directory

Content of this directory
-------------------------
### `ontodoc` templates with introductory text and document layout
* [emmo.md](emmo.md): Main template for EMMO. It includes the other
templates.
* [introduction.md](introduction.md): Introductory text.
* [relations.md](relations.md): Introduction and sections for Relations
chapter.
* [classes.md](classes.md): Introduction and sections for Classes
* [figs](figs): Figures used in the introduction.

* [emmo.md](emmo.md): Main template for EMMO.
It includes the other templates.
* [introduction.md](introduction.md): Introductory text.
* [relations.md](relations.md): Introduction and sections for Relations chapter.
* [classes.md](classes.md): Introduction and sections for Classes.
* [figs](figs): Figures used in the introduction.

### `pandoc` configuration files
* [emmodoc-meta.yaml](emmodoc-meta.yaml): Metadata for EMMO, like title,
authers, abstract, etc.
* [pandoc-options.yaml](pandoc-options.yaml): General pandoc options.
* [pandoc-html-options.yaml](pandoc-html-options.yaml): Additional pandoc options
for html generation.
* [pandoc-pdf-options.yaml](pandoc-pdf-options.yaml): Additional pandoc options
for pdf generation.
* [pandoc-html.css](pandoc-html.css): css file used for html generation.
* [pandoc-template.html](pandoc-template.html): Modified copy of the
standard pandoc html template with a small adjustment for the author list.
* [pandoc-template.tex](pandoc-template.tex): Modified copy of the
standard pandoc latex template with a small adjustment for the author list.


Using this example as a starting point for documenting your own ontology
------------------------------------------------------------------------
For simple html documentation, you can skip all input files and simply
run `ontodoc` as

ontodoc --format=simple-html YOUR_ONTO.owl YOUR_ONTO.html

It is also possible to include ontodoc templates using the --template
option for adding additional information and structure the document.
In this case the template may only contain `ontodoc` pre-processer
directives and inline html, but not markdown.

In order to produce output in pdf (or any other output format supported
by pandoc), you can write your `ontodoc` template in markdown (with
`ontodoc` pre-processer directives) and follow these steps to get started:

* Copy all the files starting with `pandoc-` to a new directory.
* Create a metadata yaml file for your ontology. You can use
[emmodoc-meta.yaml](emmodoc-meta.yaml) as a template.
* Update [pandoc-options.yaml](pandoc-options.yaml). Especially change:
- `input-files` to the name of your new yaml metadata file
- `logo` to the path of your logo (or remove it)
- `titlegraphic` to the path of your title figure (or remove it)
* Optionally add `ontodoc` template files with additional information
about your ontology and document layout.

That should be it. Good luck!

* [emmodoc-meta.yaml](emmodoc-meta.yaml): Metadata for EMMO, like title, authers, abstract, etc.
* [pandoc-options.yaml](pandoc-options.yaml): General pandoc options.
* [pandoc-html-options.yaml](pandoc-html-options.yaml): Additional pandoc options for html generation.
* [pandoc-pdf-options.yaml](pandoc-pdf-options.yaml): Additional pandoc options for pdf generation.
* [pandoc-html.css](pandoc-html.css): css file used for html generation.
* [pandoc-template.html](pandoc-template.html): Modified copy of the standard pandoc html template with a small adjustment for the author list.
* [pandoc-template.tex](pandoc-template.tex): Modified copy of the standard pandoc latex template with a small adjustment for the author list.

## Using this example as a starting point for documenting your own ontology

For simple html documentation, you can skip all input files and simply run `ontodoc` as

```console
ontodoc --format=simple-html YOUR_ONTO.owl YOUR_ONTO.html
```

It is also possible to include ontodoc templates using the `--template` option for adding additional information and structure the document.
In this case the template may only contain `ontodoc` pre-processer directives and inline html, but not markdown.

In order to produce output in pdf (or any other output format supported by pandoc), you can write your `ontodoc` template in markdown (with `ontodoc` pre-processer directives) and follow these steps to get started:

* Copy all the files starting with `pandoc-` to a new directory.
* Create a metadata YAML file for your ontology.
You can use [emmodoc-meta.yaml](emmodoc-meta.yaml) as a template.
* Update [pandoc-options.yaml](pandoc-options.yaml).
Especially change:
* `input-files` to the name of your new yaml metadata file.
* `logo` to the path of your logo (or remove it).
* `titlegraphic` to the path of your title figure (or remove it).
* Optionally add `ontodoc` template files with additional information about your ontology and document layout.

That should be it.
Good luck!
6 changes: 1 addition & 5 deletions examples/emmodoc/classes.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- markdownlint-disable-next-line MD041 -->
%%
%% This file
%% This is Markdown file, except of lines starting with %% will
Expand All @@ -10,7 +11,6 @@
(signs) that are used in the ontology. Individuals are declared by the
EMMO users when they want to apply the EMMO to represent the world.


%BRANCHHEAD EMMO
The root of all classes used to represent the world. It has two children;
*collection* and *item*.
Expand All @@ -31,11 +31,9 @@ branch of mereotopology.
%% - a fusion can be partitioned in more than one way
%BRANCH EMMO


%BRANCHDOC Elementary
%BRANCHDOC Perspective


%BRANCHDOC Holistic
%BRANCHDOC Semiotic
%BRANCHDOC Sign
Expand All @@ -46,7 +44,6 @@ branch of mereotopology.
%BRANCHDOC Icon
%BRANCHDOC Process


%BRANCHDOC Perceptual
%BRANCHDOC Graphical
%BRANCHDOC Geometrical
Expand All @@ -70,7 +67,6 @@ branch of mereotopology.
%BRANCHDOC DerivedQuantity rankdir=RL
%BRANCHDOC PhysicalConstant


%BRANCHDOC Reductionistic
%BRANCHDOC Expression

Expand Down
3 changes: 1 addition & 2 deletions examples/emmodoc/emmo.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- markdownlint-disable-next-line MD041 -->
%%
%% This is the main Markdown input file for the EMMO documentation.
%%
Expand All @@ -10,11 +11,9 @@

%INCLUDE classes.md


%HEADER Individuals level=1
%ALL individuals


%HEADER Appendix level=1

%HEADER "The complete taxonomy of EMMO relations" level=2
Expand Down
Loading

0 comments on commit 9599b9d

Please sign in to comment.