README.md 7.91 KB
Newer Older
Rieks Joosten's avatar
Rieks Joosten committed
1 2
# eSSIF-Lab Framework

Rieks Joosten's avatar
Rieks Joosten committed
3
This repo contains files that are used to generate the the [eSSIF-Lab framework](https://essif-lab.pages.grnet.gr/framework/) website, which includes the eSSIF-Lab vision, functional architecture, terminology and other relevant topics.
4

Rieks Joosten's avatar
Rieks Joosten committed
5
This website is generated using [Docusaurus 2](https://v2.docusaurus.io/) (and a custom plugin developed by [GRNET](https://grnet.gr/en/) for handling terminology).
6

Rieks Joosten's avatar
Rieks Joosten committed
7
## Writing Docusaurus Documents
8

Rieks Joosten's avatar
Rieks Joosten committed
9
Docusaurs requires documentation content to appear in `.md` files inside the `docs` folder.
10 11 12 13 14 15
Each file defines the following attributes at its very beginning:

- `id`, by which the file is referred to across the project
- `title`, appearing at the top of the file's display
- `sidebar_label`, the file's name appearing in the sidebar

Rieks Joosten's avatar
Rieks Joosten committed
16
Documentation on these and other header fields can be found [here](https://v2.docusaurus.io/docs/markdown-features#markdown-headers). 
17

Rieks Joosten's avatar
Rieks Joosten committed
18 19
The Terminology Engine plugin of GRNET uses additional header fields. These are (or will be) defined [here](./docs/terminology-contributions).

20
The `sidebars.js` file contains the basic mechanism for [distributing content among sections](https://v2.docusaurus.io/docs/docs-introduction#sidebar) and is self-explanatory (compare with the sidebar appearing [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/project)). Subsections within the `.md` file (that is, tagged with `##`) will appear at the right part of the page (see for example [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/infrastructure)).
Rieks Joosten's avatar
Rieks Joosten committed
21 22 23

## Inserting Images in docs
<!-- **DEPRECATED** Images must be put inside the directory `static/images` and developers must refer to them using _relative_ urls.
24 25 26
Example: ![eSSIF-Lab logo](../images/eSSIF-Lab%20logo.png)
Docusaurus knows that the `../images` directory is inside the `static` directory, and thus process correctly.
The deployment pipe will convert `../images/` in such links to their _*absolute*_ urls.
Rieks Joosten's avatar
Rieks Joosten committed
27 28 29 30 31 32 33 34 35 36 37 38 39
Of course, if you want to link to images on the web, you can still use absolute urls. -->

If you want to add an image, say `example.png`, here is what you do:
- first, add the image to the `/static/images` directory (or `/static/images/subdir-path/`)
- then, in your document, add a line behind the docusaurus header that says: `import useBaseUrl from '@docusaurus/useBaseUrl';`
- next, in your document, at the place where you want the image to be presented, insert the following snippet:
```html
<img
  alt="text-that-shows-if-the-image-cannot-be-found"
  src={useBaseUrl('images/example.png')}
/>
```
(or `src={useBaseUrl('images/subdir-path/example.png')}` if you added the image file there).
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54

### Installation

You must be able to use `yarn` in order to run the local development server. If
you face an error similar to `ERROR: There are no scenarios; must have at least one`,
refer [here](https://github.com/yarnpkg/yarn/issues/2821) for a correct
re-installation of `yarn`.

### Local Development

```
$ yarn
$ yarn start
```

fmerg's avatar
fmerg committed
55
The first command is for linking dependencies. The second starts a local development server and opens up a browser window.
56 57
Note that not all browsers work with this - for example, Microsoft Edge doesn't work. Chrome and FireFox however do.
When developing, most changes are reflected live without having to restart the server.
58 59 60 61 62 63 64 65 66 67 68

### Build

```
$ yarn build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.

### Deployment

fmerg's avatar
fmerg committed
69
Just push your changes to the `master` branch and they will be automatically deployed at https://essif-lab.pages.grnet.gr/framework/
70

71
## Terminology/Glossary plugin usage
72 73 74

This project has a plugin integrated that can generate terms in a useful way so contributors can write a special syntax to reference terms and generate a glossary based on those terms.

fmerg's avatar
fmerg committed
75 76 77
This plugin is designed to work in the pre-build stage. This means, it is strongly suggested that you do **not** run manually
the script in your local computer (or at least do not commit changes). In order to view the final result, you can instead use
Docker and/or Docker Compose, as follows.
78

fmerg's avatar
fmerg committed
79
#### Docker
80 81 82 83 84 85 86 87 88 89 90 91

You can run the following commands to see the output of the website, just as it will look like when deployed to a production environment:

```
docker build -t essif-lab-terminology:latest .
docker run -ti -p 5000:5000 essif-lab-terminology:latest
```

You can then visit http://localhost:5000 to view the website

To stop docker from running, you can just hit `ctrl+c` in the terminal window.

fmerg's avatar
fmerg committed
92
#### Docker Compose
93 94 95 96 97 98 99 100 101 102

Docker Compose is a wrapper of docker, so you can run less commands to do the same job as you would do with docker commands. You only need to run:

```
docker-compose up --force-recreate --build
```

and then visit http://localhost:5000 to view the website.

To stop docker-compose, just like docker, hit `ctrl+c` in the terminal window.
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141

## Terminology/Glossary plugin explanation

### How it works

This plugin parses docs in two ways:

  1. Parses all `*.mdx` files under `docs/` and replaces each pattern with an
  appropriate React component supporting a tooltip functionality (see below)
  2. Generates a glossary with all terms corresponding to the `*.md` files under `docs/terms/`.

Parses all markdown files and generates a glossary page with all the pattern terms found in the .md files

### Replace patterns with dynamical elements

When writing docs, in order to refer to a term, you may use the following syntax:

```
%%term_text|term_name%%
```

where:
- `term_text`: The terminology text you want it to be visible in the documentation
page
- `term_name`: The filename of the term file, which resides under `./docs/terms` directory.

inside `docs/*.mdx` files. After successfully running the script, the above occurrence
will be replaced by a React component, which will render `term_text` as a link to the
corresponding term page, which is in turn generated from the `term_name` attribute;
furthermore, *hovering* over `term_text` displays a term summary, as extracted from the
corresponding term page.

### Example usage

Say you want to reference a term that exists under the `./docs/terms/` directory,
e.g. `./docs/terms/party.md`. You can use the following syntax to reference
this term in your documentation page:

```
142
Some content that wants to reference the %%party|party%% term
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
```

When the script runs, this will be replaced as follows:

```
Some content that wants to reference the <Term reference="party" popup="Popup text">Party</Term> term
```

which supports the functionality explained above.

### How to correctly write a term

This plugin assumes that you follow the structure, as explained below:

Each term should have its own `.md` file, inside the `./docs/terms` directory,
and it needs to consist of the following structure:

```title="./docs/terms/term.md"
---
id: term
title: Term page
Rieks Joosten's avatar
Rieks Joosten committed
164
hoverText: "This hover text will appear in the documentation page that you reference this term."
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206
---

### Term explanation

content here
```

> Pay attention to the `hoverText` attribute, as it's important to provide this
>attribute (along with the default docusaurus attributes), so the plugin can
>fetch the correct popup text to show when referencing a term.

### Running the script

When you are finished referencing terms and have written corresponding term pages,
you can test this locally by running the following command:

```.shell script
$ yarn parse
yarn run v1.22.5
 docusaurus parse
Replacing patterns with <Term />
Done in 1.41s.
```

This will replace all `%%term_text|term_name%%` occurrences with the React component
supporting the required functionality.

### Generate the glossary page

If everything works well with the above procedure, you can then generate a
glossary page, by running the following command:

```.shell script
$ yarn glossary
yarn run v1.22.5
 docusaurus glossary
Alphabetical list of terms
Done in 1.53s.
```

This will generate a file in `./docs/glossary.md` where every term that has been
mentioned above, will be populated in the `glossary.md` page.