@@ -321,16 +321,22 @@ To bypass the checks (to save or get feedback on work-in-progress) use
321
321
322
322
The documentation for tskit is written using
323
323
[ Sphinx] ( http://www.sphinx-doc.org/en/stable/ )
324
- and contained in the ` docs ` directory. It is written in the
325
- [ reStructuredText] ( http://docutils.sourceforge.net/rst.html ) format and
326
- deployed automatically to [ readthedocs] ( https://readthedocs.org/ ) .
324
+ and contained in the ` docs ` directory. The files in this directory are
325
+ markdown files that serve as an input to [ jupyterbook] ( https://jupyterbook.org/ ) ,
326
+ which allows jupyter notebook code, primarily in Python, to be automatically
327
+ executed and the output inserted before deployment. The docs are then
328
+ deployed automatically to the [ tskit.dev website] ( https://tskit.dev/ ) .
327
329
API documentation for both Python and C are generated automatically from
328
- source.
330
+ source: documentation embedded in the source code makes use of sphinx and
331
+ the [ reStructuredText] ( http://docutils.sourceforge.net/rst.html ) format to
332
+ alloow formating and cross referencing.
329
333
For the C code, a combination of [ Doxygen] ( http://www.doxygen.nl/ )
330
334
and [ breathe] ( https://breathe.readthedocs.io/en/latest/ ) is used to
331
335
generate API documentation.
332
336
333
- Please help us to improve the documentation!
337
+ Please help us to improve the documentation! You can check on the list of
338
+ [ documentation issues] ( https://github.com/tskit-dev/tskit/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation )
339
+ on GitHub, and help us fix any, or add issues for anything that's wrong or missing.
334
340
335
341
336
342
### Small edits
@@ -673,6 +679,7 @@ Vim users may find the
673
679
[ vim-clang-format] ( https://github.com/rhysd/vim-clang-format )
674
680
plugin useful for automatically formatting code.
675
681
682
+
676
683
### Building
677
684
678
685
We use [ meson] ( https://mesonbuild.com ) and [ ninja-build] ( https://ninja-build.org ) to
@@ -704,32 +711,6 @@ For vim users, the [mesonic](https://www.vim.org/scripts/script.php?script_id=53
704
711
simplifies this process and allows code to be compiled seamlessly within the
705
712
editor.
706
713
707
- (sec_development_c_static_analysis)=
708
-
709
- ### Static analysis
710
-
711
- After running `` ninja -C build `` , we can easily run some static analysis tools
712
- which are useful for detecting bugs (although there is usually a lot of
713
- false-positive noise also).
714
-
715
- We can run [ clang-tidy] ( https://clang.llvm.org/extra/clang-tidy/ ) like this:
716
-
717
- ``` bash
718
- $ clang-tidy -p build/compile_commands.json tskit/* .c
719
- ```
720
-
721
- We can run [ scan-build] ( https://github.com/rizsotto/scan-build ) which also
722
- generates some HTML reports. First, install from `` pypi `` :
723
-
724
- ``` bash
725
- $ python -m pip install scan-build
726
- ```
727
-
728
- Then run
729
-
730
- ``` bash
731
- $ analyze-build --cdb build/compile_commands.json --exclude tests --exclude subprojects
732
- ```
733
714
734
715
### Unit Tests
735
716
0 commit comments