Doc fixes - Githubissues

JuliaGeometry / GeometryBasics.jl

Basic Geometry Types

MIT License

164 stars 54 forks source link

Doc fixes #129

Closed knuesel closed 3 years ago

knuesel commented 3 years ago

Remove mention of distance fields (there's nothing about them in the code)
Fix the duplicate references
Convert the quickstart example to doc @repl blocks (and add a mention of GeometryBasics.mesh)
Add CI doc step, calling doctest() so an error is reported if doctests fail

Feel free to squash the commits before merging...

Fixes #119, fixes #128

SimonDanisch commented 3 years ago

Lovely :)

knuesel commented 3 years ago

Forgot to mention: there are two links in primitives.md that I converted to link-less text because no docstring exist for them:

GeometryPrimitive
AbstractSimplex

I thought I'd let someone competent add docstrings for these...

Also I'm not sure about the mention of GeometryBasics.mesh: should the doc rather advertise triangle_mesh?

mforets commented 3 years ago

Bump? Nice work @knuesel ! Thanks for fixing the build warnings from the issue I opened last week (#128). About the remaining docs issues, I assume they can be added in subsequent PRs ;)

hyrodium commented 3 years ago

Thanks! I'm really looking forward to this PR being merged!

@knuesel Could you resolve the conflicts of README.md? I think we can't use @repl block in README.md because that is for GitHub repository page. We have two options:

Remove most of contents from README.md, and replace them with the link to the document.
Remove copying README, and add new page for quick start in the document.

I think the first option is recommended.

SimonDanisch commented 3 years ago

Damn totally forgot about this PR! Would be nice to merge it ;) Let me know if I can help with anything!

knuesel commented 3 years ago

Thanks for the bump @hyrodium . I separated the README and index.md as suggested:

The quickstart is now in index.md which is its own file (not copied from the README)
The README links to the documentation and adds information specific to developers (e.g. how to build the documentation)

I also updated the doctests and CI config to expect output from Julia 1.6.

@SimonDanisch for me this is ready to be merged.

hyrodium commented 3 years ago

Thanks for the fixes! Nice contribution:tada:

knuesel commented 3 years ago

Ah @SimonDanisch one thing you might want to consider: maybe you'd prefer to have @repl blocks in metadata.md, instead of jldoctest blocks which might be annoying to maintain?

See here for the changes I had to make for Julia 1.6. It was quick to do with doctest(GeometryBasics, fix=true) but it adds some friction.

On the other hand you might prefer to keep the jldoctests to check that things behave as expected?

knuesel commented 3 years ago

I went ahead and converted the jldoctests to @repl blocks (easier to maintain).

@SimonDanisch I think we're good?

SimonDanisch commented 3 years ago

Cool, thanks a lot! :)