diff --git a/doc/Makefile b/doc/Makefile index 59576f7..f72a9fc 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -57,7 +57,7 @@ html: @echo "Generating Doxygen documentation..." doxygen Doxyfile @echo "Doxygen documentation generated. \n" - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + $(SPHINXBUILD) -b html -c ./ $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/doc/sphinx/source/conf.py b/doc/conf.py similarity index 98% rename from doc/sphinx/source/conf.py rename to doc/conf.py index 5980f57..d717aa0 100644 --- a/doc/sphinx/source/conf.py +++ b/doc/conf.py @@ -36,7 +36,7 @@ extensions = [ 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', - 'breathe', +# 'breathe', ] # Add any paths that contain templates here, relative to this directory. @@ -292,7 +292,7 @@ texinfo_documents = [ #texinfo_no_detailmenu = False #Breathe configuration -sys.path.append( "../breathe/" ) -breathe_projects = { "OBITools3": "../doxygen/xml/" } +sys.path.append( "breathe/" ) +breathe_projects = { "OBITools3": "doxygen/xml/" } breathe_default_project = "OBITools3" diff --git a/doc/sphinx/source/DMS.rst b/doc/source/DMS.rst similarity index 82% rename from doc/sphinx/source/DMS.rst rename to doc/source/DMS.rst index 54e5f3f..cda5d02 100644 --- a/doc/sphinx/source/DMS.rst +++ b/doc/source/DMS.rst @@ -13,7 +13,7 @@ Up to now, each of these categories of data were stored in separate files, and nothing made it mandatory to keep them together. -The `Data Management System` (DMS) of OBITools3 can be regarded as a basic +The `Data Management System` (DMS) of OBITools3 can be viewed like a basic database system. @@ -27,9 +27,7 @@ OBIDMS UML An OBIDMS directory contains : * one `OBIDMS history file <#obidms-history-files>`_ - * Two different kinds of directories : - * OBIDMS column directories - * OBIDMS column group directories containing OBIDMS column directories + * OBIDMS column directories OBIDMS column directories @@ -39,16 +37,9 @@ OBIDMS column directories contain : * all the different versions of one OBIDMS column, under the form of different files (`OBIDMS column files <#obidms-column-files>`_) * one `OBIDMS version file <#obidms-version-files>`_ -The directory name is the column attribute, or sub-attribute if the column directory is in a column group directory. +The directory name is the column attribute with the extension ``.obicol``. - -OBIDMS column group directories -=============================== - -OBIDMS column group directories contain OBIDMS column directories. They are used to store dictionary-like data, where -each key corresponds to an OBIDMS column. - -The directory name is the dictionary attribute. Each key is considered a sub-attribute and is associated to its column. +Example: ``count.obicol`` OBIDMS column files @@ -57,7 +48,7 @@ OBIDMS column files Each OBIDMS column file contains : * a header of a size equal to a multiple of PAGESIZE (PAGESIZE being equal to 4096 bytes on most systems) containing metadata - * one column of data with the same `OBIType `_ + * Lines of data with the same `OBIType `_ Header @@ -79,7 +70,14 @@ The header of an OBIDMS column contains : Data ---- -A column of data with the same `OBIType `_. +A line of data corresponds to a vector of elements. Each element is associated with an element name. +Elements names are stored in the header. The correspondance between an element and its name is done +using their order in the lists of elements and elements names. This structure allows the storage of +dictionary-like data. + +Example: In the header, the attribute ``elements_names`` will be associated with the value ``"sample_1; +sample_2;sample_3"``, and a line of data with the type ``OBInt_t`` will be stored as an ``OBInt_t`` vector +of size three e.g. ``5|8|4``. Mandatory columns @@ -158,3 +156,5 @@ operations ever done in the OBIDMS directory and the views in between them : .. image:: ./images/history.png :width: 150 px :align: center + + diff --git a/doc/source/UML/OBIDMS_UML.png b/doc/source/UML/OBIDMS_UML.png new file mode 100644 index 0000000..edf59c0 Binary files /dev/null and b/doc/source/UML/OBIDMS_UML.png differ diff --git a/doc/sphinx/source/UML/OBITypes_UML.class.violet.html b/doc/source/UML/OBITypes_UML.class.violet.html similarity index 100% rename from doc/sphinx/source/UML/OBITypes_UML.class.violet.html rename to doc/source/UML/OBITypes_UML.class.violet.html diff --git a/doc/sphinx/source/UML/OBITypes_UML.png b/doc/source/UML/OBITypes_UML.png similarity index 100% rename from doc/sphinx/source/UML/OBITypes_UML.png rename to doc/source/UML/OBITypes_UML.png diff --git a/doc/source/UML/ObiDMS_UML.class.violet.html b/doc/source/UML/ObiDMS_UML.class.violet.html new file mode 100644 index 0000000..7c038dc --- /dev/null +++ b/doc/source/UML/ObiDMS_UML.class.violet.html @@ -0,0 +1,1874 @@ + + + + + + + + + This file was generated with Violet UML Editor 2.1.0. +   ( View Source / Download Violet ) +
+
+ +
+
+ embedded diagram image + + \ No newline at end of file diff --git a/doc/sphinx/source/containers.rst b/doc/source/containers.rst similarity index 100% rename from doc/sphinx/source/containers.rst rename to doc/source/containers.rst diff --git a/doc/sphinx/source/data.rst b/doc/source/data.rst similarity index 56% rename from doc/sphinx/source/data.rst rename to doc/source/data.rst index 22ddae7..effff99 100644 --- a/doc/sphinx/source/data.rst +++ b/doc/source/data.rst @@ -2,8 +2,8 @@ Data in OBITools3 ################# -The OBITools3 inaugure a new way to manage DNA metabarcoding data. -They rely on a `Data management System` (DMS) that can be considered as +The OBITools3 introduce a new way to manage DNA metabarcoding data. +They rely on a `Data management System` (DMS) that can be viewed like a simplified database system. diff --git a/doc/sphinx/source/elementary.rst b/doc/source/elementary.rst similarity index 100% rename from doc/sphinx/source/elementary.rst rename to doc/source/elementary.rst diff --git a/doc/sphinx/source/guidelines.rst b/doc/source/guidelines.rst similarity index 92% rename from doc/sphinx/source/guidelines.rst rename to doc/source/guidelines.rst index 7e5f348..7a0574a 100644 --- a/doc/sphinx/source/guidelines.rst +++ b/doc/source/guidelines.rst @@ -70,7 +70,7 @@ Tickets should always be labeled with the branches for which they are relevant. Documentation ************* -C functions are documented in the header files. +C functions are documented in the header files for public functions, and in the source file for private functions. ************** @@ -92,7 +92,7 @@ C99 : * Object layer * OBITools3 library -`Python 3 `_ : +`Python 3.5 `_ : * Top layer code (scripts) For the documentation, `Sphinx `_ should be used for both the original @@ -111,6 +111,8 @@ Enum members, macros, constants: ``ALL_CAPS`` Functions, local variables: ``lower_case`` +Public functions: ``obi_lower_case`` + Functions that shouldn't be called directly: ``_lower_case`` (``_`` prefix) Global variables: ``g_lower_case`` (``g_`` prefix) @@ -120,9 +122,6 @@ Pointers: ``pointer_ptr`` (``_ptr`` suffi .. note:: Underscores are used to delimit 'words'. -.. todo:: - ``obi_function`` for public functions names? - ***************** Programming rules diff --git a/doc/sphinx/source/images/history.png b/doc/source/images/history.png similarity index 100% rename from doc/sphinx/source/images/history.png rename to doc/source/images/history.png diff --git a/doc/sphinx/source/images/version_control.png b/doc/source/images/version_control.png similarity index 100% rename from doc/sphinx/source/images/version_control.png rename to doc/source/images/version_control.png diff --git a/doc/sphinx/source/index.rst b/doc/source/index.rst similarity index 93% rename from doc/sphinx/source/index.rst rename to doc/source/index.rst index 4de01c7..1f8b861 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/source/index.rst @@ -11,7 +11,6 @@ OBITools3 documentation Programming guidelines Data structures - Pistes de reflexion Indices and tables diff --git a/doc/sphinx/source/specialvalues.rst b/doc/source/specialvalues.rst similarity index 76% rename from doc/sphinx/source/specialvalues.rst rename to doc/source/specialvalues.rst index c8b8d0e..d2f145e 100644 --- a/doc/sphinx/source/specialvalues.rst +++ b/doc/source/specialvalues.rst @@ -7,13 +7,16 @@ NA values ========= All OBITypes have an associated NA (Not Available) value. -NA values are implemented by specifying an explicit NA value for each type, corresponding to the R standards: +NA values are implemented by specifying an explicit NA value for each type, +corresponding to the R standards as much as possible: -* For the types ``OBIInt_t``, ``OBIBool_t``, ``OBIIdx_t`` and ``OBITaxid_t``, the NA value is ``INT_MIN``. +* For the type ``OBIInt_t``, the NA value is ``INT_MIN``. -* For the type ``OBIChar_t``: the NA value is ``\0`` (?). +* For the type ``OBIBool_t``, the NA value is ``2``. -* For the type ``OBIStr_t`` : the NA value is ``\0`` (?). +* For the type ``OBIIdx_t`` and ``OBITaxid_t``, the NA value is ``SIZE_MAX``. + +* For the type ``OBIChar_t``: the NA value is ``\0``. * For the type ``OBIFloat_t``:: @@ -29,7 +32,7 @@ NA values are implemented by specifying an explicit NA value for each type, corr x.word[hw] = 0x7ff00000; x.word[lw] = 1954; return x.value; - } + } Minimum and maximum values for ``OBIInt_t`` diff --git a/doc/sphinx/source/types.rst b/doc/source/types.rst similarity index 100% rename from doc/sphinx/source/types.rst rename to doc/source/types.rst diff --git a/doc/sphinx/source/UML/OBIDMS_UML.png b/doc/sphinx/source/UML/OBIDMS_UML.png deleted file mode 100644 index b6dc312..0000000 Binary files a/doc/sphinx/source/UML/OBIDMS_UML.png and /dev/null differ diff --git a/doc/sphinx/source/UML/ObiDMS_UML.class.violet.html b/doc/sphinx/source/UML/ObiDMS_UML.class.violet.html deleted file mode 100644 index 8fc2ddc..0000000 --- a/doc/sphinx/source/UML/ObiDMS_UML.class.violet.html +++ /dev/null @@ -1,1864 +0,0 @@ - - - - - - - - - This file was generated with Violet UML Editor 2.1.0. -   ( View Source / Download Violet ) -
-
- -
-
- embedded diagram image - - \ No newline at end of file diff --git a/doc/sphinx/source/pistes.rst b/doc/sphinx/source/pistes.rst deleted file mode 100644 index aa981fd..0000000 --- a/doc/sphinx/source/pistes.rst +++ /dev/null @@ -1,23 +0,0 @@ -################### -Pistes de reflexion -################### - - -****************************** -Ce que l'on veut pouvoir faire -****************************** - - * Gerer les valeurs manquantes - * Modifier une colonne en cours d'ecriture (mmap) - * Ajouter des valeurs a la fin du fichier d'une colonne en cours d'ecriture (mmap) - - -****** -Divers -****** - -* Si l'ordre d'une colonne est change, elle est reecrite (pas d'index). -* Utilisation de semaphores pour la lecture -* Utilisation de tas pour l'indexation des chaines de caracteres. Chaque colonne dont - le type est OBIStr_t est stockee dans 3 fichiers : un fichier contenant les chaines, un - fichier contenant les index, et un fichier contenant le tas.