What recommended tools to publish user manual in GitHub WiKi

Tooling
,
1

I wrote a large scientific package SoilWater-ToolBox https://github.com/joseph-pollacco/SoilWaterToolbox and now it is time to write the user’s manual which we plan to publish in GitHub. I am looking for advice on the recommended tools to write a complex manual which will describe the model :smiley::

1. Is GitHub wiki the recommended website to write a manual?

2.  Is there a recommended template?

3.  How can we write Latex equations?

4. What would be the recommended Markdown editor OpenSource or paid?

Many thanks for helping me to get started.

2 Likes
2

  1. yes

  2. a package like Documenter.jl is usually used to generate the files, but there are alternatives

  3. LaTeX Syntax · Documenter.jl

  4. most editors are fine for Markdown, it is plain text after all. Just use whatever you use for Julia coding.

4 Likes
3

The advantage of Documenter is that you can “reuse” the docstrings of your functions/types for yhe API part, and use true julia scripts, that you can keep under testing, with Literate.jl for the “tutorials”/'exemple" part of the documentation.

In practice, Literate.jl converts julia scripts (.jl) with markdown embedded as comment to markdown files (.md) with code embedded as example block, and then Documenter transfrorms everything to html and integrates with GitHub Continuous integration to piblish on github pages.

3 Likes
4

By the way, as you work on soil topics, you may be interested in this conference:

1 Like
5

I had a quick look on the repository. I think before looking at the documentation, you should reorganise the code as a standard Julia package.

You could have a look on my tutorial on how to develope a package: 11 - Developing Julia packages - Julia language: a concise tutorial

1 Like
6

Thanks Antonello Labianco. I could now see the advantages of using Documenter.jl as it can use partly the docstrings of the functions and therefore enables not to duplicate the efforts and to reinforce good programming practice to document the functions.

7

@sylvaticus Not the OP, but thanks for the tutorial on packages. Answered a few of my lingering questions.

1 Like
8

TUTUORIALS/ TEMPLATES / VIDEOS ON USING LITERATE .JL & DOCUMENTER.JL

I had a quick look at Literate.jl
https://github.com/fredrikekre/Literate.jl
& Documenter.jl
https://juliadocs.github.io/Documenter.jl/stable/

Which indeed these software are very powerful software. I am wandering if there are some Tutorials or Videos or simple example templates which can help beginners to get started quickly?

As the proposed examples are good but may be overhelming for a beginner?
Examples
https://juliadocs.github.io/Documenter.jl/stable/man/examples/#Examples

Thanks for providing to the community such a powerful tool.

9

What is the best Markdown software which is best to use for a beginner and has Latex?

For example in Extensions in Vscode there are a multitude of options, but I do not think that there are any ones which has dedicated pulldown menus or options which will help beginners get started.

10

@sylvaticus thanks I totally agree that I will need to make the SoiulWater-ToolBox into a package, I would write a dedicated topic to answer some of my questions.

11

@sylvaticus The conference looks very interesting :smiley: Yes I am French scientist but working in New-Zealand.

12

My suggestion, after having struggled with that is to copy the structure of the docs of some package and modify files accordingly.

To publish, I have a detailed step by step here: Publish Docs · JuliaNotes.jl

This package (JuliaNotes.jl) , by the way, is only docs, thus the structure can’t get much simpler than that. That is a good one to copy.

4 Likes
13

I integrate the two in the way I described in my own BetaML package, you can have a look on the docs folder and the .github/workflows one, where scripts for GitHub CI are defined.

1 Like