[Discussion] Documentation-Issues

[briederer]

As mentioned in #4 we'll use this issue to discuss further documentation issues.
Things to be done:

• Compat for docs/Project.toml (done: Added CompatHelper docs-subdir #7)
• Set up github page (done: CI for Documentation and tests #10)
• Set up CI to create docs at push to master and deploy (done: CI for Documentation and tests #10)

Anything else?

Edit: 25.05.2021

• stable docs for first release
• add package again to docs/Project.toml when registered

[fzierler]

Seems like all the julia projects I saw which use these kind of separation don't have any [compat] sections at all in the docs/Project.toml.

See StatsBase.jl for an example of a [compat] section in the docs. As long as we don't use any doctests I don't think that we urgently need CompatHelper. The only package that could change substantially is DocumenterCitations.jl and even then Pkg.jl should easily figure out which version of Documenter.jl should be used.

[briederer]

You are right.
We will see if CompatHelper adds a PR automatically and otherwise we could add it by hand for DocumenterCitations.jl if necessary.

[briederer]

I have activated the website for now but it is not working yet.
We still need to setup the right directory (docs/site) for deploying the webpage and the CI. Also as long as CI is not set up we could simply add the output files of Documenter.jl to the specific folder.

[fzierler]

I will look into setting up the Github CI and Codecov using PackageTemplates.jl. I will try to set up CI for 64bit Linux, Mac and Windows. In case we run into any problems we can still restrict CI to a subset of it.

[briederer]

I would prefer Ubuntu and Mac to be working and Windows as a bonus (since I guess none of us uses windows?)
I am looking right now into the Github CI so I would suggest that you have a look at CodeCov first and also maybe already registering via Registrator.jl because I read that this may take some time to be approved.

[fzierler]

I would wait with registering the package until we have a useful minimal working package (let's say including effective masses, some fits and plots and so on) and we can tag version 0.1.

[fzierler]

It seems that the docs are not linked correctly. Clicking on the link in the repo redirects on a 404 page.

[briederer]

This is expected since the link points to the stable-version which would be the most recent release, which we do not have created yet.
For the docs which refer to the master branch one needs to add /dev to the url.

[fzierler]

Thanks, I missed that. In that case please disregard my latest PR.

[briederer]

For the docs which refer to the master branch one needs to add /dev to the url.

Also while a PR is open it is possible to look at the docs created by this PR by adding previews/PR$(PRNUMBER) to the url.

[briederer]

Added now the workflow for keeping gh-pages branch clear.
When pushing to master (independently if they originate from a PR or are directly pushed) the preview pages for all mentioned PRs (i.e. all #VAL) will be deleted.