diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..0027f28 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..9534b01 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/about.rst b/docs/source/about.rst new file mode 100644 index 0000000..7524937 --- /dev/null +++ b/docs/source/about.rst @@ -0,0 +1,96 @@ + +===== +About +===== + +A Python library for writing SciData_ JSON-LD_ files. + +.. _SciData: http://stuchalk.github.io/scidata/ +.. _JSON-LD: https://json-ld.org/ + +SciData and JSON-LD +------------------- + +JSON-LD is a convenient (human-readable) encoding of Resource +Desctiption Framework (RDF) triples. However, unlike traditional +relational databases (e.g., MySQL), the graph has no schema. This +is problematic as including data from different sources results +in a system with no common way to search across the data. The +SciData framework is a structure for users to add data and its metadata +that are organized in the graph through the associated SciData ontology. + +There are three main sections of the SciData framework: + +* the methodology section (describing how the research was done) +* the system section (describing what the research studied and the conditions) +* the dataset section (the experimental data, plus any derived or supplemental + data) + +The methodology and system sections are generic and users can add any data +they need to contextualize the dataset. However, in addition they must +provide a JSON-LD context file to semantically describe the data elements +included. The dataset section has predefined data structures (dataseries, +datagroup, and datapoint) although other strudtures can be included +if needed. + +Translating the content in JSON-LD. Referencing the JSON-LD below: + +* '@context': provides resources that define the context (meaning) of + data elements in the document (as a JSON array). It consists of + three sections: + + - a list of one or more 'context' files + - a JSON object containing one or more definitions of namespaces + used in the document + - a JSON object with one entry '@base' that defines the base URL + to be prepended to all internal references (i.e. '@id' entries) +* root level '@id': the 'name' of the file and where ingested into a + graph database, the graph name +* '@graph': the definition of content that will be represented as triples + and identified by the graph name (this is therfore a 'quad') +* '@id' under '@graph': the identifier for the graph. The scidatalib + code uses the '@base' to populate this, so they are consistent. As a result, + all node identifiers '@id's in the document are globally unique because the + '@base' is unique. + +Example JSON-LD:: + + { + "@context": [ + "https://stuchalk.github.io/scidata/contexts/scidata.jsonld", + { + "sci": "https://stuchalk.github.io/scidata/ontology/scidata.owl#" + }, + { + "@base": "https://my.research.edu//" + } + ], + "@id": "file_identifier", + "generatedAt": "/", + "@type": "sdo:scidataFramework", + "uid": "", + "scidata": { + "@type": "sdo:scientificData", + "methodology": { + "@id": "methodology/", + "@type": "sdo:methodology", + "aspects": [] + }, + "system": { + "@id": "system/", + "@type": "sdo:system", + "facets": [] + }, + "dataset": { + "@id": "dataset/", + "@type": "sdo:dataset", + "dataseries": [], + "datagroup": [], + "datapoint": [] + } + } + } + } diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..ff94bd2 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,79 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'SciDataLib' +copyright = '2021, Dylan Johnson, Marshall McDonnell, and Stuart Chalk' +author = 'Dylan Johnson, Marshall McDonnell, and Stuart Chalk' + +# The short X.Y version +version = '0.2' +# The full version, including alpha/beta/rc tags +release = '0.2' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.imgmath', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..2829562 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. SciDataLib documentation master file, created by + sphinx-quickstart on Tue Apr 13 11:39:44 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to SciDataLib's documentation! +====================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/setup.cfg b/setup.cfg index 68fc46b..07e1fd1 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,15 +1,15 @@ [metadata] # replace with your username: name = SciDataLib -version = 0.1.0 +version = 0.2 url = https://github.com/ChalkLab/SciDataLib -author = 'Dylan Johnson, Stuart Chalk' -author_email = 'n01448636@unf.edu, schalk@unf.edu' +author = 'Dylan Johnson, Marshall McDonnell, Stuart Chalk' +author_email = 'n01448636@unf.edu, mcdonnellmt@ornl.gov, schalk@unf.edu' classifiers = Programming Language :: Python :: 3 License :: OSI Approved :: MIT License Operating System :: OS Independent -description = Python library for development of SciData JSON-LD files +description = Python library for creation of SciData JSON-LD files long_description = file: README.md long_description_content_type = text/markdown diff --git a/setup.py b/setup.py index f1869d9..1352bac 100644 --- a/setup.py +++ b/setup.py @@ -6,9 +6,9 @@ setuptools.setup( name="SciDataLib", - version="0.1.0", - author="Dylan Johnson, Stuart Chalk", - author_email="n01448636@unf.edu, schalk@unf.edu", + version="0.2", + author="Dylan Johnson, Marshall McDonnell, Stuart Chalk", + author_email="n01448636@unf.edu, mcdonnellmt@ornl.gov, schalk@unf.edu", description="Python library for development of SciData JSON-LD files", long_description=long_description, long_description_content_type="text/markdown",