docs: Convert Knora base ontology doc to RST. #289
Conversation
| @@ -31,6 +31,7 @@ | |||
| # ones. | |||
| extensions = [ | |||
| 'sphinx.ext.todo', | |||
| 'sphinx.ext.graphviz' | |||
There was a problem hiding this comment.
graphviz has to be installed on the system first (e.g. brew install graphviz for Mac OS X or sudo apt-get install graphviz for Debian-based Linux distros).
Could please add that to the installation instructions in the docs/README? Or will those requirements be met otherwise by running another program that takes conf.py as its input?
However, their website http://www.sphinx-doc.org/en/stable/ext/graphviz.html says:
Since this setting is not portable from system to system, it is normally not useful to set it in conf.py
| @@ -31,6 +31,7 @@ | |||
| # ones. | |||
| extensions = [ | |||
| 'sphinx.ext.todo', | |||
There was a problem hiding this comment.
What happened to the TODOs (including their reference to open issues)?
| Resource Description Framework (RDF) | ||
| ------------------------------------ | ||
|
|
||
| Knora uses a hierarchy of ontologies based on the Resource Description |
There was a problem hiding this comment.
We used to explain what Knora stands for: Knowledge Organization, Representation, and Annotation, http://knora.org
But maybe since this is not a standalone document anymore, we can assume that the reader has learned about that in another section.
| any substring in the text by giving its start and end positions. [#]_ | ||
| For example, suppose we have the following text: | ||
|
|
||
| This sentence has overlapping visual attributes. |
There was a problem hiding this comment.
This sentence should be formatted (see
)
|
I did the initial conversion with pandoc, then converted the diagrams and references manually.
I disabled the Sphinx TODO plugin several months ago because it makes a mess on the front page of the documentation (for each TODO, it shows the absolute path to the original file on the computer where the documentation was generated). There were just two TODOs left in
I'll add something about that to the README.
Yes, it's already explained in
Unfortunately that's not possible in RST, because inline markup cannot be nested. That's why I changed the following sentence to explain the intended effect. |
|
Ok, I fixed the formatting using raw HTML. http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw-data-pass-through Maybe this causes problems for other output formats using LaTeX. |
|
In general, the conversion to LaTeX seems to have some problems (TOC only given for the ontology documentation, but with missing page numbers; problems with images; problems with Unicode chars). This is not new though. RST to LaTeX never passed through properly. |
|
Maybe we should just write all the documentation directly in HTML. :) |
|
I added issue #293 for |
|
möörge |
…ip/beol * 'develop' of https://github.com/dhlab-basel/Knora: Update README.md test (webapi): add E2E testing (#244) BEOL and bibliography ontologies (#283) refactor (webapi): migrate spray to akka http (#273) fix (sipi error message): display the error message returned by SIPI (#287) Add support for editing labels and value comments (#261) docs: Convert Knora base ontology doc to RST. (#289) relative paths (#288) removing relative paths to icons in css file: it doesn't survive an front apache proxy like: (#191) adding css and fonts used in the js/jquery.editvalue.js (#180) docs: Add remark about pyvenv for anaconda users on mac and linux (#264) add internal link to doc/readme (#278) docs (extended search): add missing explanations for LIKE and !LIKE (#279) Upgrade the built-in Fuseki to version 2.4.0 (#268) # Conflicts: # knora-ontologies/knora-base.ttl # webapi/src/test/scala/org/knora/webapi/responders/v1/OntologyResponderV1Spec.scala
This converts the LaTeX file documenting the Knora base ontology to reStructuredText, and integrates it with the rest of the Knora documentation.