Documentation

[szabo137]

⚠️ This issue is very similar to the issue 42 of the minterpy package.

It is proposed to enhance the documentation of QEDbase.jl by applying parts of the Divio documentation system. This contains the following categories, which should be reflected in the sections of the documentation:

Landing page

This short page introduces the user to the purpose of QEDbase.jl and briefly shows the installation procedure.

How-tos

In this part, the more problem-oriented part of the documentation is presented. This means, here one defines a short and concrete problem and shows the solution using QEDbase.jl. This also contains a section on how to extend QEDbase.jl, e.g. by implementing custom four-momentum types. Consider using Literate.jl to build this section (see here for details).

Mathematical explanations

As the section title suggests, this part contains the mathematical background used for the implementations. Actually, this is not restricted to the math itself, but also to explanations of design choices, based on (but not only) mathematical statements.

References for the API

This is the information-focused part of the documentation. It contains the description of each function and type exported from QEDbase.jl, which will be achieved by using docstrings and the functionality of Documenter.jl. This part may be separated into a part for users (i.e. the top-level API) and a part for developers (i.e. the low-level API/functionality).

Changes to the divio system

In the divio system, there is an additional section Tutorials which is learning-oriented. However, this will be covered in the main documentation of QED.jl.

Final remarks

This documentation will be part of the QED.jl documentation and will be included via the MultiDocumenter.jl package (see here for details).

[AntonReinhard]

Also should fix this warning by setting the repo keyword in the makedocs call to an actual repository. I believe github repositories are supported out of the box.

┌ Warning: Unable to determine the repository root URL for the navbar link.
│ This can happen when a string is passed to the `repo` keyword of `makedocs`.
│ 
│ To remove this warning, either pass a Remotes.Remote object to `repo` to completely
│ specify the remote repository, or explicitly set the remote URL by setting `repolink`
│ via `makedocs(format = HTML(repolink = "..."), ...)`.
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/9kOxY/src/html/HTMLWriter.jl:707

[SimeonEhrig]

Also should fix this warning by setting the repo keyword in the makedocs call to an actual repository. I believe github repositories are supported out of the box.

┌ Warning: Unable to determine the repository root URL for the navbar link.
│ This can happen when a string is passed to the `repo` keyword of `makedocs`.
│ 
│ To remove this warning, either pass a Remotes.Remote object to `repo` to completely
│ specify the remote repository, or explicitly set the remote URL by setting `repolink`
│ via `makedocs(format = HTML(repolink = "..."), ...)`.
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/9kOxY/src/html/HTMLWriter.jl:707

I will fix it now. I start to add a documentation build job. During this, I will also fix this issue.

[SimeonEhrig]

I opened the PR: #28