Skip to content

Demo for a structured collection of terms and relations based on Sphinx and RST files

License

Notifications You must be signed in to change notification settings

uellue/fairmat-term-relations

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

fairmat-term-relations is a demo for a structured collection of terms and relations based on Sphinx and RST files.

Installation

  • Clone this repo
  • Set up a Python environment
  • Install the required packages: pip install -r requirements.txt

Build

Note

Many features and tags in README.rst don't work stand-alone, but only if this file is embedded in index.rst and built with the rest of the project!

How it works

  • Terms are defined as individual files in ./source/terms/.
  • An overview of terms is generated with a table of content in :ref:`terms`.
  • Relation between terms are defined in :ref:`relations`. This can be structured in smaller units as well by splitting it in files, just like the terms, if desired.
  • The main document ./source/index.rst provides an overview.

Features

  • BibTeX bibliography and citations like so: :cite:`clausen_alexander_2021_5547992`.
  • Intersphinx links such as :ref:`numpy:whatisnumpy`. Entries here are also linkable from other Sphinx documentation in the same way, once the documentation is online.
  • Links to Issues or Pull Requests on GitHub like :issue:`1`, for example.
  • Human-readable and accessible, can easily be built to documents in various formats
  • Can be machine-readable if a defined form is kept for entries. Possibly, entries can be pre-compiled from another source of truth, like for example author information in LiberTEM that is compiled from a JSON file.
  • Suitable for GitHub-based collaborative editing since individual files for entries avoid merge conflicts.
  • Many more Sphinx features available if desired, such as testing code examples and/or building documentation from Jupyter notebooks.

Acknowledgments

Based on the changelog infrastructure of LiberTEM.

About

Demo for a structured collection of terms and relations based on Sphinx and RST files

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published