You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+176-2
Original file line number
Diff line number
Diff line change
@@ -41,7 +41,6 @@ To bring up the openEASE docker containers, run this:
41
41
docker-compose up
42
42
```
43
43
44
-
45
44
### Troubleshooting
46
45
**KnowRob** container is created when user is loggedIn. Incase of connection can not be established to the KnowRob container, one needs to take a look at knowrob container logs.
47
46
@@ -55,7 +54,6 @@ If above command fails then it is most likely that the KnowRob container is not
55
54
docker logs dockerbridge
56
55
```
57
56
58
-
59
57
#### Other docker problems
60
58
In some situations it may help to start again with a clean docker installation. This requires removing all containers and images. You can do that using following commands:
61
59
@@ -64,3 +62,179 @@ In some situations it may help to start again with a clean docker installation.
64
62
docker rm $(docker ps -a -q)
65
63
docker rmi $(docker images -q)
66
64
```
65
+
66
+
## Content
67
+
68
+
### Neem-Overview Pages
69
+
70
+
The homepage features certain neems and allows direct access to their knowledge base or overview page. The overview page just renders the README markdown file of the neem's repository.
71
+
72
+
The homepage shows two fixed neems at the top, and below that the six most recently updated neems (based on the last commit to their respective repositories).
73
+
74
+
The server fetches the READMEs every three hours.
75
+
76
+
#### Information for NeemGit Maintainers
77
+
78
+
The README should at least contain the following:
79
+
80
+
- title
81
+
- author of the neem
82
+
- general description
83
+
- acknowledgement for fundings etc.
84
+
85
+
Furthermore, here are some suggestions for more things to include:
86
+
87
+
- details about the data or dataset used
88
+
- how to access the data
89
+
- license
90
+
- references
91
+
92
+
Check out existing READMEs or overview pages for reference or structure. Make sure to keep the READMEs up-to-date.
93
+
94
+
- Maintainers need to have a markdown file named 'README.md' in their repositories or their neem cannot be featured on the homepage (they will still appear on the neemhub page). The markdown should explain about the neem. For reference, have a look at READMEs of other.
95
+
- Relevant publications need to be listed in said README. Currently they cannot be linked automatically to the neem.
96
+
- If a unordered list is not rendered properly, make sure it has leading and trailing empty line in the README:
97
+
```markdown
98
+
some text
99
+
100
+
- a
101
+
- b
102
+
- c
103
+
104
+
more text
105
+
```
106
+
- Most elements of the README files should be rendered correctly. It might happen that some elements will not pass the renderer because of the HTML-sanitizer. If that happens, those element tags need to be added to the list of allowed tags in `get_sanitizer()` (s. `pages/neem_overview.py`). It might be necessary to adjust css styling in `static/css/overview.scss`.
107
+
108
+
#### Technical Details
109
+
110
+
For updates, the server will first get the list of neems for the neemhub. Next it will check the repository of each of these neems for a README. If one can be found, it will be fetched and stored locally. The repositories of each neem is then checked for the time of the last update. Neems are then sorted by this timestamp, in order to select the six most recent neems to display on the homepage. The featured neems at the top of the homepage are identified by their neem-id. Meanwhile information about the neem and location of the related files will be stored in the postgres database.
111
+
112
+
During an update, previous information will be overwritten (except for default files, those are kept separately).
113
+
114
+
115
+
### Publications Pages
116
+
117
+
The publications page features papers related to the EASE project. The page includes the information of the bibtex entry for each paper and, if available, also the paper itself.
118
+
119
+
The server fetches the bibtex-files and papers (pdfs compiled into a zip-file) once a day.
120
+
121
+
#### Information for BibTEX-Entries of Publications
122
+
123
+
Make sure to follow regular guidelines for the type of publication (such as IEEE, etc.).
124
+
125
+
A few points of attention nonetheless:
126
+
127
+
- **Syntax**
128
+
129
+
Check the syntax of the entry to be correct. The parser for the `bibtex`-files, `pybtex`, sadly is very unforgiving (s. [Possible Errors when Parsing bibtex-files](#possible-errors-when-parsing-bibtex-files)). [TEXfaq](https://texfaq.org/) is a valuable resource.
130
+
131
+
- **Authors**
132
+
133
+
One common error is the faulty listing of authors. Author names need to be listed in either of the following forms:
134
+
135
+
- First Last
136
+
- Last, First
137
+
- Last, Suffix, First
138
+
139
+
Furthermore they need to be separated with `and`. An example for a correct listing:
140
+
141
+
``` latex
142
+
AUTHOR = {Jamie Blond and Peter Brooks and Michael Blue}
143
+
```
144
+
145
+
Check out [this page](https://texfaq.org/FAQ-manyauthor) for more information.
146
+
147
+
- **Title Capitalization**
148
+
149
+
Unfortunately titles of publications, journals, etc. need to manually be set in the `bibtex`-entry in order to be properly displayed on the website. Python 2.7 itself only offers very rudimentary methods for capitalization of titles, and libraries such as [titlecase](https://pypi.org/project/titlecase/) do not support Python 2.7.
150
+
151
+
Generally, letters, words, or phrases encased with curly brackets `{}` will be displayed as written (in terms of capitalizaton):
152
+
153
+
``` latex
154
+
title = {A {Study} about {Smart Robots}}
155
+
```
156
+
157
+
You can read more about this topic [here](https://texfaq.org/FAQ-capbibtex).
158
+
159
+
#### Possible Errors when Parsing bibtex-files
160
+
161
+
The server uses [`pybtex`](https://pybtex.org/) for parsing the bibtex-files. Said library is very sensitive when it comes to the syntax and will fail to parse even on a single error. Other parsers had different problems, overall `pybtex` was still the preferred choice.
162
+
163
+
You can use the [following](https://github.com/navidJadid/publications-bibtex-tester) tool to check if a given bibtex-file would cause errors when parsed by the server.
164
+
165
+
[TEXfaq](https://texfaq.org/) also offers answers to commonly asked questions about this topic.
166
+
167
+
#### Technical Details
168
+
169
+
For updates, first an url for both the `publications.bib` and `papers.zip` need to be provided (s. [Content Settings page](#content-settings-page)). The former contains information about all EASE related publications. Only a subset of those will be displayed on the publications page later. To be specific, those which have the following keywords in their `bibtex`-entries:
170
+
171
+
- openease_overview
172
+
- openease_kb_of_exp_data
173
+
- openease_cram
174
+
- openease_knowledge_representation
175
+
- openease_perception
176
+
- openease_human_activity
177
+
- openease_manipulation
178
+
- openease_natural_language
179
+
180
+
The `bib`-file will be parsed and stored in a python dictionary. Also for each entry, the program checks if a paper is available as a pdf (from `papers.zip`) and links it, if available.
181
+
182
+
During an update, previous information will be overwritten (except for default files, those are kept separately).
183
+
184
+
185
+
### News Blog
186
+
187
+
The news blog is currently hardcoded.
188
+
In the future a content-management-system for the blog will be set up. A guide will follow then.
189
+
190
+
191
+
### Content-Settings Page
192
+
193
+
The content-settings page shows the state of all the content for the neem-overview and publications pages. It shows:
194
+
195
+
- state of content loaded (none, default, latest)
196
+
- state of the update jobs (active, paused)
197
+
- time of next update
198
+
- time of previous update
199
+
- type of previous update (automatic, manual)
200
+
201
+
In addition, the following action can be performed:
202
+
203
+
- manually load updates for the content
204
+
- pause and resume update jobs for the content
205
+
- load default files for any given content type
206
+
- turn on/off to download 'default_papers.zip`
207
+
- turn on/off to prepare downloadable files for the admin (these include the papers, markdowns, python dictionaries for neem-overview or publications data as JSON)
208
+
- set developer settings (= deactivate unneeded functionalities)
209
+
- download 'content files' (s. [How to Update Default Files](#how-to-update-default-files))
210
+
211
+
Lastly, the content-settings page is where the url or local path for the publications `bibtex` and `papers.zip` need to be set. If using the local path, provide the relative paths to `/content/publications-and-papers/` in the settings panel and place the mentioned files there.
212
+
213
+
At least the `bibtex` file needs to be provided, otherwise the publications files cannot be updated. Urls need to start with 'http(s)://'.
214
+
215
+
Each function is provided with a tooltip to explain it's function.
216
+
217
+
#### Developer Settings
218
+
219
+
The server will load debug settings for the content,
220
+
if the environment variable 'EASE_DEBUG' is set to 'true'. That includes:
221
+
222
+
- upon start-up, either previously loaded content or default content is loaded (=faster start-up); no updates for neem-overview and publications are fetched
223
+
- update jobs are set to paused
224
+
- 'download default papers' is set to 'OFF'
225
+
- 'prepare downloadable files' is set to 'OFF'
226
+
227
+
In DEBUG mode, changes to those settings persist even after the lifetime of the container. This is useful if certain behaviours need to be examined upon restarting or rebuilding the container (otherwise these settings would need to be manually set each time). If you made some settings previously, but want the stock developer settings again, just click 'load developer settings' on the content-settings page.
228
+
229
+
#### Production Settings
230
+
231
+
If the environment variable 'EASE_DEBUG' is set to 'false#, the server will load production settings for the content. That includes:
232
+
233
+
- upon start-up, updates for neem-overview and publications are fetched
234
+
- update jobs are set to active
235
+
- 'download default papers' is set to 'ON'
236
+
- 'prepare downloadable files' is set to 'ON'
237
+
238
+
#### How to Update Default Files
239
+
240
+
Default files follow the internal structure given by the program. Therefore, the easiest way to update them (for example, to include newer neem overviews or publications), is to fetch the latest updates on a running server, while having checked `prepare downloadable files`. Next, download the files of choice and replace the appropriate files in this repository.
"description": "Episodic memories of a human operator performing fetch and place tasks in a simulated environment by controlling an avatar mimicking the body of a human."
0 commit comments