Preconditioners.jl icon indicating copy to clipboard operation
Preconditioners.jl copied to clipboard

Add initial Literate documentation

Open JeffFessler opened this issue 3 years ago • 4 comments

I am looking for an incomplete Cholesky decomposition precoditioner and I found this package. To help others (and myself) figure out how to use this code some docs would be helpful. Here is a PR with at least some basics.

JeffFessler avatar Nov 06 '22 19:11 JeffFessler

I don't know Literate enough to review this. But it seems CI isn't giving a preview of the docs.

mohdibntarek avatar Nov 07 '22 01:11 mohdibntarek

But it seems CI isn't giving a preview of the docs.

I forgot to include the CI for the docs. It is added now. There are settings to force the CI to make a preview of the docs but I don't usually use that because it seems to make the repo get larger. I check the preview locally by running julia --project=. make.jl in the docs/ directory. But to make it easier for you, for now I changed the one line in make.jl to be push_preview = true so now it should build a doc preview.

The docs are not too exciting now because this package has so few docstrings...

JeffFessler avatar Nov 07 '22 01:11 JeffFessler

BTW, the docs will deploy only if someone who is a maintainer enables github pages with appropriate ssh deploy keys under Settings tab. See https://documenter.juliadocs.org/stable/man/hosting/#GitHub-Actions

JeffFessler avatar Nov 07 '22 01:11 JeffFessler

I tried to manually create a gh-pages branch at the command line and push that. Then I reran the CI. The CI ran, but did not create any preview in the gh-pages branch. I think it can work only if the maintainers set that up under Settings, and then rerun the workflow.

JeffFessler avatar Nov 07 '22 02:11 JeffFessler

I setup the keys. Let's see.

mohdibntarek avatar Feb 25 '23 08:02 mohdibntarek

You can now preview the docs at https://julialinearalgebra.github.io/Preconditioners.jl/previews/PR31

mohdibntarek avatar Feb 25 '23 08:02 mohdibntarek

Now it also shows up in the checks under documenter/deploy which you can click to preview the docs.

mohdibntarek avatar Feb 25 '23 09:02 mohdibntarek

I see that it is running all the CI tests, even when only docs are changed. Eventually the CI file should be updated to prevent that...

JeffFessler avatar Feb 25 '23 21:02 JeffFessler

I forgot to update the README with links to the docs. It will be a while before I have time to do that though.

JeffFessler avatar Jun 21 '23 14:06 JeffFessler