Skip to content

Commit 8c0321a

Browse files
jeromekelleherjeromekelleher
authored
Merge pull request #43 from jeromekelleher/docs-initial
First outline of the documentation.
2 parents d1bc5e0 + e178273 commit 8c0321a

22 files changed

+5115
-9
lines changed

‎.circleci/config.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ jobs:
100100
# ./build-clang/malloc_tests
101101
# ./build-clang/io_tests
102102

103-
# - run:
104-
# name: Build docs
105-
# command: |
106-
# cd docs && make
103+
- run:
104+
name: Build docs
105+
command: |
106+
cd docs && make

‎c/tsk_core.h‎

Lines changed: 38 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file tsk_core.h
3+
* @brief Core utilities used in all of tskit.
4+
*/
15
#ifndef __TSK_CORE_H__
26
#define __TSK_CORE_H__
37

@@ -53,7 +57,6 @@
5357
TSK_CHECK_SITE_DUPLICATES | TSK_CHECK_MUTATION_ORDERING | TSK_CHECK_INDEXES)
5458

5559
/* Flags for dump tables */
56-
/* #define TSK_ALLOC_TABLES 1 */
5760

5861
/* Flags for load tables */
5962
#define TSK_BUILD_INDEXES 1
@@ -69,21 +72,51 @@
6972
#define TSK_FILE_FORMAT_VERSION_MAJOR 12
7073
#define TSK_FILE_FORMAT_VERSION_MINOR 0
7174

72-
/* Error codes */
75+
/**
76+
@defgroup GENERAL_ERROR_GROUP General errors.
77+
@{
78+
*/
7379

74-
/* General errrors */
80+
/**
81+
Generic error thrown when no other message can be generated.
82+
*/
7583
#define TSK_ERR_GENERIC -1
84+
/**
85+
Memory could not be allocated.
86+
*/
7687
#define TSK_ERR_NO_MEMORY -2
88+
/**
89+
An IO error occured.
90+
*/
7791
#define TSK_ERR_IO -3
7892
#define TSK_ERR_BAD_PARAM_VALUE -4
7993
#define TSK_ERR_BUFFER_OVERFLOW -5
8094
#define TSK_ERR_UNSUPPORTED_OPERATION -6
8195
#define TSK_ERR_GENERATE_UUID -7
96+
/** @} */
97+
98+
/**
99+
@defgroup FILE_FORMAT_ERROR_GROUP File format errors.
100+
@{
101+
*/
82102

83-
/* File format errors */
103+
/**
104+
A file could not be read because it is in the wrong format
105+
*/
84106
#define TSK_ERR_FILE_FORMAT -100
107+
/**
108+
The file is in tskit format, but the version is too old for the
109+
library to read. The file should be upgraded to the latest version
110+
using the ``tskit upgrade`` command line utility.
111+
*/
85112
#define TSK_ERR_FILE_VERSION_TOO_OLD -101
113+
/**
114+
The file is in tskit format, but the version is too new for the
115+
library to read. To read the file you must upgrade the version
116+
of tskit.
117+
*/
86118
#define TSK_ERR_FILE_VERSION_TOO_NEW -102
119+
/** @} */
87120

88121
/* Out of bounds errors */
89122
#define TSK_ERR_BAD_OFFSET -200
@@ -139,6 +172,7 @@
139172
#define TSK_ERR_SIMPLIFY_MIGRATIONS_NOT_SUPPORTED -801
140173
#define TSK_ERR_NONBINARY_MUTATIONS_UNSUPPORTED -802
141174

175+
142176
/* This bit is 0 for any errors originating from kastore */
143177
#define TSK_KAS_ERR_BIT 14
144178

‎c/tsk_tables.h‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file tsk_tables.h
3+
* @brief Tskit Tables API.
4+
*/
15
#ifndef TSK_TABLES_H
26
#define TSK_TABLES_H
37

@@ -99,6 +103,9 @@ typedef struct {
99103
/* Table definitions */
100104
/****************************************************************************/
101105

106+
/**
107+
@brief The individual table.
108+
*/
102109
typedef struct {
103110
tsk_tbl_size_t num_rows;
104111
tsk_tbl_size_t max_rows;
@@ -116,6 +123,9 @@ typedef struct {
116123
tsk_tbl_size_t *metadata_offset;
117124
} tsk_individual_tbl_t;
118125

126+
/**
127+
@brief The node table.
128+
*/
119129
typedef struct {
120130
tsk_tbl_size_t num_rows;
121131
tsk_tbl_size_t max_rows;
@@ -131,6 +141,9 @@ typedef struct {
131141
tsk_tbl_size_t *metadata_offset;
132142
} tsk_node_tbl_t;
133143

144+
/**
145+
@brief The site table.
146+
*/
134147
typedef struct {
135148
tsk_tbl_size_t num_rows;
136149
tsk_tbl_size_t max_rows;
@@ -148,6 +161,9 @@ typedef struct {
148161
tsk_tbl_size_t *metadata_offset;
149162
} tsk_site_tbl_t;
150163

164+
/**
165+
@brief The mutation table.
166+
*/
151167
typedef struct {
152168
tsk_tbl_size_t num_rows;
153169
tsk_tbl_size_t max_rows;
@@ -167,6 +183,9 @@ typedef struct {
167183
tsk_tbl_size_t *metadata_offset;
168184
} tsk_mutation_tbl_t;
169185

186+
/**
187+
@brief The edge table.
188+
*/
170189
typedef struct {
171190
tsk_tbl_size_t num_rows;
172191
tsk_tbl_size_t max_rows;
@@ -177,6 +196,9 @@ typedef struct {
177196
tsk_id_t *child;
178197
} tsk_edge_tbl_t;
179198

199+
/**
200+
@brief The migration table.
201+
*/
180202
typedef struct {
181203
tsk_tbl_size_t num_rows;
182204
tsk_tbl_size_t max_rows;
@@ -189,6 +211,9 @@ typedef struct {
189211
double *time;
190212
} tsk_migration_tbl_t;
191213

214+
/**
215+
@brief The population table.
216+
*/
192217
typedef struct {
193218
tsk_tbl_size_t num_rows;
194219
tsk_tbl_size_t max_rows;
@@ -200,6 +225,9 @@ typedef struct {
200225
tsk_tbl_size_t *metadata_offset;
201226
} tsk_population_tbl_t;
202227

228+
/**
229+
@brief The provenance table.
230+
*/
203231
typedef struct {
204232
tsk_tbl_size_t num_rows;
205233
tsk_tbl_size_t max_rows;
@@ -216,10 +244,16 @@ typedef struct {
216244
tsk_tbl_size_t *record_offset;
217245
} tsk_provenance_tbl_t;
218246

247+
/**
248+
@brief The table collection.
249+
*/
219250
typedef struct {
251+
/** @brief The sequence length defining the tree sequence's coordinate space */
220252
double sequence_length;
221253
char *file_uuid;
254+
/** @brief The individual table */
222255
tsk_individual_tbl_t *individuals;
256+
/* TODO document other public members */
223257
tsk_node_tbl_t *nodes;
224258
tsk_edge_tbl_t *edges;
225259
tsk_migration_tbl_t *migrations;
@@ -438,7 +472,32 @@ int tsk_provenance_tbl_get_row(tsk_provenance_tbl_t *self, size_t index, tsk_pro
438472
/* Table collection .*/
439473
/****************************************************************************/
440474

475+
/**
476+
@brief Allocate a new table collection.
477+
478+
@rst
479+
After allocation, each of the consituent tables is allocated with the default size increment.
480+
The sequence length is set to zero.
481+
@endrst
482+
483+
@param self A pointer to an uninitialised tsk_tbl_collection_t object.
484+
@param flags Allocation time options. Currently unused.
485+
@return Return 0 on success or a negative value on failure.
486+
*/
441487
int tsk_tbl_collection_alloc(tsk_tbl_collection_t *self, int flags);
488+
489+
/**
490+
@brief Load a table collection from file.
491+
492+
@rst
493+
Reads a table collection from the specified file.
494+
@endrst
495+
496+
@param self A pointer to an uninitialised tsk_tbl_collection_t object.
497+
@param filename A NULL terminated string containing the filename.
498+
@param flags Load time options. Currently unused.
499+
@return Return 0 on success or a negative value on failure.
500+
*/
442501
int tsk_tbl_collection_load(tsk_tbl_collection_t *self, const char *filename, int flags);
443502
int tsk_tbl_collection_dump(tsk_tbl_collection_t *tables, const char *filename, int flags);
444503
int tsk_tbl_collection_copy(tsk_tbl_collection_t *self, tsk_tbl_collection_t *dest);

‎c/tsk_trees.h‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file tsk_trees.h
3+
* @brief Tskit core tree sequence operations.
4+
*/
15
#ifndef TSK_TREES_H
26
#define TSK_TREES_H
37

@@ -15,7 +19,9 @@ extern "C" {
1519
#define TSK_DIR_REVERSE -1
1620

1721

18-
/* Tree sequences */
22+
/**
23+
@brief The tree sequence object.
24+
*/
1925
typedef struct {
2026
size_t num_trees;
2127
size_t num_samples;
@@ -104,8 +110,35 @@ typedef struct {
104110
/* Tree sequence.*/
105111
/****************************************************************************/
106112

113+
/**
114+
@brief Allocate a new tree sequence from a table collection.
115+
116+
@rst
117+
A tree sequence is a read-only view of a table collection with extra
118+
structures that facilitate efficient tree iteratation and other operations.
119+
@endrst
120+
121+
@param self A pointer to an uninitialised tsk_treeseq_t object.
122+
@param tables A pointer to a tsk_tbl_collection_t object.
123+
@param flags Allocation time options.
124+
@return Return 0 on success or a negative value on failure.
125+
*/
107126
int tsk_treeseq_alloc(tsk_treeseq_t *self, tsk_tbl_collection_t *tables, int flags);
127+
128+
/**
129+
@brief Load a tree sequence from file.
130+
131+
@rst
132+
Reads a tree sequence from the specified file.
133+
@endrst
134+
135+
@param self A pointer to an uninitialised tsk_treeseq_t object.
136+
@param filename A NULL terminated string containing the filename.
137+
@param flags Load time options. Currently unused.
138+
@return Return 0 on success or a negative value on failure.
139+
*/
108140
int tsk_treeseq_load(tsk_treeseq_t *self, const char *filename, int flags);
141+
109142
int tsk_treeseq_dump(tsk_treeseq_t *self, const char *filename, int flags);
110143
int tsk_treeseq_copy_tables(tsk_treeseq_t *self, tsk_tbl_collection_t *tables);
111144
int tsk_treeseq_free(tsk_treeseq_t *self);

‎c/tskit.h‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @file tskit.h
3+
* @brief Tskit API.
4+
*/
15
#ifndef __TSKIT_H__
26
#define __TSKIT_H__
37

‎docs/Makefile‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS = -W
6+
SPHINXBUILD = sphinx-build
7+
SOURCEDIR = .
8+
BUILDDIR = _build
9+
10+
DOXYGEN_XML=doxygen/xml
11+
12+
all: ${DOXYGEN_XML}
13+
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
${DOXYGEN_XML}: ../c/tskit.h
16+
cd doxygen && doxygen
17+
18+
# Put it first so that "make" without argument is like "make help".
19+
help:
20+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21+
22+
# .PHONY: help Makefile
23+
24+
# # Catch-all target: route all unknown targets to Sphinx using the new
25+
# # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
26+
# %: Makefile
27+
# @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/_static/README‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Placeholder file to keep git happy.

‎docs/c-api.rst‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
.. _sec_c_api:
2+
3+
=====
4+
C API
5+
=====
6+
7+
.. warning::
8+
**This section is under construction, incomplete and experiemental!!**
9+
10+
**********
11+
Tables API
12+
**********
13+
14+
.. doxygenstruct:: tsk_tbl_collection_t
15+
:members:
16+
17+
.. doxygenfunction:: tsk_tbl_collection_alloc
18+
19+
.. doxygenfunction:: tsk_tbl_collection_load
20+
21+
**************
22+
Tree sequences
23+
**************
24+
25+
.. doxygenstruct:: tsk_treeseq_t
26+
:members:
27+
28+
.. doxygenfunction:: tsk_treeseq_alloc
29+
30+
.. doxygenfunction:: tsk_treeseq_load
31+
32+
33+
*********
34+
Constants
35+
*********
36+
37+
.. _sec_c_api_error_codes:
38+
39+
--------------
40+
Generic Errors
41+
--------------
42+
43+
.. doxygengroup:: GENERAL_ERROR_GROUP
44+
:content-only:
45+
46+
------------------
47+
File format errors
48+
------------------
49+
50+
.. doxygengroup:: FILE_FORMAT_ERROR_GROUP
51+
:content-only:
52+
53+
54+
.. todo:: Add in groups for rest of the error types and document.

‎docs/changelogs.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. _sec_changelogs:
2+
3+
==========
4+
Changelogs
5+
==========
6+
7+
******
8+
Python
9+
******
10+
11+
.. include:: ../python/CHANGELOG.rst
12+
13+
*****
14+
C API
15+
*****
16+
17+
.. include:: ../c/CHANGELOG.rst

0 commit comments

Comments
 (0)