Merge pull request #129 from knuesel/doc-fixes

Doc fixes

Author: SimonDanisch

.github/workflows/ci.yml

@@ -48,12 +48,18 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@v1
         with:
-          version: '1.5'
+          version: '1.6'
       - run: |
           julia --project=docs -e '
             using Pkg
             Pkg.develop(PackageSpec(path=pwd()))
             Pkg.instantiate()'
+      - run: |
+          julia --project=docs -e '
+            using Documenter: doctest, DocMeta
+            using GeometryBasics
+            DocMeta.setdocmeta!(GeometryBasics, :DocTestSetup, :(using GeometryBasics); recursive=true)
+            doctest(GeometryBasics)'
       - run: julia --project=docs docs/make.jl
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -4,3 +4,4 @@
 .DS_Store
 /Manifest.toml
 docs/build/
+*~

README.md

@@ -2,101 +2,36 @@
 [![Build Status](https://api.travis-ci.org/JuliaGeometry/GeometryBasics.jl.svg?branch=master)](https://travis-ci.com/JuliaGeometry/GeometryBasics.jl)
 [![Codecov](https://codecov.io/gh/JuliaGeometry/GeometryBasics.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaGeometry/GeometryBasics.jl)
 
-**Documentation**:
 [![Docs - stable](https://img.shields.io/badge/docs-stable-lightgrey.svg)](http://juliageometry.github.io/GeometryBasics.jl/stable/)
-[![Docs - dev](https://img.shields.io/badge/docs-dev-blue.svg)](http://juliageometry.github.io/GeometryBasics.jl/dev)
+[![Docs - dev](https://img.shields.io/badge/docs-dev-blue.svg)](http://juliageometry.github.io/GeometryBasics.jl/dev/)
 
 # GeometryBasics.jl
 
-Basic Geometry Types.
-This package aims to offer a standard set of Geometry types, which easily work with metadata, query frameworks on geometries and different memory layouts.
-The aim is to create a solid basis for Graphics/Plotting, finite elements analysis, Geo applications, and general geometry manipulations - while offering a julian API, that still allows performant C-interop.
+Basic geometry types.
 
-This package is a replacement for the discontinued [GeometryTypes](https://github.com/JuliaGeometry/GeometryTypes.jl/).
-
-## Quick start
-
-```julia
-using GeometryBasics
-
-# create some points
-julia> p1 = Point(3, 1)
-2-element Point{2,Int64} with indices SOneTo(2):
- 3
- 1
-
-julia> p2 = Point(1, 3);
-
-julia> p3 = Point(4, 4);
-
-# geometries can carry metadata
-julia> poi = meta(p1, city="Abuja", rainfall=1221.2)
-2-element PointMeta{2,Int64,Point{2,Int64},(:city, :rainfall),Tuple{String,Float64}} with indices SOneTo(2):
- 3
- 1
-
-# metadata is stored in a NamedTuple and can be retrieved as such
-julia> meta(poi)
-(city = "Abuja", rainfall = 1221.2)
-
-# specific metadata attributes can be directly retrieved
-julia> poi.rainfall
-1221.2
+This package aims to offer a standard set of geometry types that easily work
+with metadata, query frameworks on geometries and different memory layouts. The
+aim is to create a solid basis for graphics/plotting, finite element analysis,
+geo applications, and general geometry manipulations - while offering a Julian
+API that still allows performant C-interop.
 
-# to remove the metadata and keep only the geometry, use metafree
-julia> metafree(poi)
-2-element Point{2,Int64} with indices SOneTo(2):
- 3
- 1
-
-# for other geometries metatypes are predefined
-julia> multipoi = MultiPointMeta([p1], city="Abuja", rainfall=1221.2)
-1-element MultiPointMeta{Point{2,Int64},MultiPoint{2,Int64,Point{2,Int64},Array{Point{2,Int64},1}},(:city, :rainfall),Tuple{String,Float64}}:
-[3, 1]
-
-# connect the points with lines
-julia> l1 = Line(p1, p2)
-Line([3, 1] => [1, 3])
-
-julia> l2 = Line(p2, p3);
-
-# connect the lines in a linestring
-julia> LineString([l1, l2])
-2-element LineString{2,Int64,Point{2,Int64},Array{GeometryBasics.Ngon{2,Int64,2,Point{2,Int64}},1}}:
- Line([3, 1] => [1, 3])
- Line([1, 3] => [4, 4])
-
-# linestrings can also be constructed directly from points
-julia> LineString([p1, p2, p3])
-2-element LineString{2,Int64,Point{2,Int64},Base.ReinterpretArray{GeometryBasics.Ngon{2,Int64,2,Point{2,Int64}},1,Tuple{Point{2,Int64},Point{2,Int64}},TupleView{Tuple{Point{2,Int64},Point{2,Int64}}, 1}}}:
- Line([3, 1] => [1, 3])
- Line([1, 3] => [4, 4])
+This package is a replacement for the discontinued [GeometryTypes](https://github.com/JuliaGeometry/GeometryTypes.jl/).
 
-# the same goes for polygons
-julia> Polygon(Point{2, Int}[(3, 1), (4, 4), (2, 4), (1, 2), (3, 1)])
-Polygon{2,Int64,Point{2,Int64},LineString{2,Int64,Point{2,Int64},Base.ReinterpretArray{GeometryBasics.Ngon{2,Int64,2,Point{2,Int64}},1,Tuple{Point{2,Int64},Point{2,Int64}},TupleView{Tuple{Point{2,Int64},Point{2,Int64}}, 1}}},Array{LineString{2,Int64,Point{2,Int64},Base.ReinterpretArray{GeometryBasics.Ngon{2,Int64,2,Point{2,Int64}},1,Tuple{Point{2,Int64},Point{2,Int64}},TupleView{Tuple{Point{2,Int64},Point{2,Int64}}, 1}}},1}}(GeometryBasics.Ngon{2,Int64,2,Point{2,Int64}}[Line([3, 1] => [4, 4]), Line([4, 4] => [2, 4]), Line([2, 4] => [1, 2]), Line([1, 2] => [3, 1])], LineString{2,Int64,Point{2,Int64},Base.ReinterpretArray{GeometryBasics.Ngon{2,Int64,2,Point{2,Int64}},1,Tuple{Point{2,Int64},Point{2,Int64}},TupleView{Tuple{Point{2,Int64},Point{2,Int64}}, 1}}}[])
+**Documentation:** http://juliageometry.github.io/GeometryBasics.jl/stable/
 
-# create a rectangle placed at the origin with unit widths
-julia> rect = Rect(Vec(0.0, 0.0), Vec(1.0, 1.0))
-GeometryBasics.HyperRectangle{2,Float64}([0.0, 0.0], [1.0, 1.0])
+## Contributing
 
-# decompose the rectangle into two triangular faces
-julia> rect_faces = decompose(TriangleFace{Int}, rect)
-2-element Array{NgonFace{3,Int64},1}:
- TriangleFace(1, 2, 4)
- TriangleFace(1, 4, 3)
+Make sure your changes don't break the documentation.
 
-# decompose the rectangle into four vertices
-julia> rect_vertices = decompose(Point{2, Float64}, rect)
-4-element Array{Point{2,Float64},1}:
- [0.0, 0.0]
- [1.0, 0.0]
- [0.0, 1.0]
- [1.0, 1.0]
+To build the documentation locally, you first need to instantiate the `docs/` project:
 
-# combine the vertices and faces into a triangle mesh
-julia> mesh = Mesh(rect_vertices, rect_faces)
-Mesh{2, Float64, Triangle}:
- Triangle([0.0, 0.0], [1.0, 0.0], [1.0, 1.0])
- Triangle([0.0, 0.0], [1.0, 1.0], [0.0, 1.0])
 ```
+julia --project=docs/
+pkg> instantiate
+pkg> dev .
+```
+
+Then use `julia --project=docs/ docs/make.jl` to build the documentation. This
+will also run the doctests defined in Markdown files. The doctests should be
+written for the Julia version configured in [ci.yml](.github/workflows/ci.yml)
+(`:docs` section).

docs/make.jl

@@ -6,12 +6,18 @@ using GeometryBasics
 
 DocMeta.setdocmeta!(GeometryBasics, :DocTestSetup, :(using GeometryBasics); recursive=true)
 
-# Copy the README to serve as the homepage
-cp(joinpath(@__DIR__, "..", "README.md"), joinpath(@__DIR__, "src", "index.md"))
-
-makedocs(format=Documenter.HTML(), sitename="GeometryBasics.jl",
-         pages=["index.md", "primitives.md", "rectangles.md", "polygons.md", "meshes.md",
-                "decomposition.md", "distancefields.md", "metadata.md", "api.md"],
+makedocs(format=Documenter.HTML(prettyurls=get(ENV, "CI", "false") == "true"),
+         sitename="GeometryBasics.jl",
+         pages=[
+                "index.md",
+                "primitives.md",
+                "rectangles.md",
+                "polygons.md",
+                "meshes.md",
+                "decomposition.md",
+                "metadata.md",
+                "api.md"
+               ],
          modules=[GeometryBasics])
 
 deploydocs(repo="github.com/JuliaGeometry/GeometryBasics.jl.git", push_preview=true)

docs/src/decomposition.md

@@ -1,9 +1,9 @@
 # Decomposition
 
 
-## GeometryBasic Mesh interface
+## GeometryBasics Mesh interface
 
-GeometryBasic defines an interface, to decompose abstract geometries into
+GeometryBasics defines an interface to decompose abstract geometries into
 points and triangle meshes.
 This can be done for any arbitrary primitive, by overloading the following interface:
 
@@ -39,7 +39,7 @@ m = GeometryBasics.mesh(Tesselation(rect, (50, 50)))
 length(coordinates(m)) == 50^2
 ```
 
-As you can see, `coordinates` and `faces` is also defined on a mesh
+As you can see, `coordinates` and `faces` are also defined on a mesh
 ```julia
 coordinates(m)
 faces(m)

docs/src/distancefields.md

@@ -0,0 +1,108 @@
+# GeometryBasics.jl
+
+Basic geometry types.
+
+This package aims to offer a standard set of geometry types that easily work
+with metadata, query frameworks on geometries and different memory layouts. The
+aim is to create a solid basis for graphics/plotting, finite element analysis,
+geo applications, and general geometry manipulations - while offering a Julian
+API that still allows performant C-interop.
+
+This package is a replacement for the discontinued [GeometryTypes](https://github.com/JuliaGeometry/GeometryTypes.jl/).
+
+## Quick start
+
+Create some points:
+
+```@repl quickstart
+using GeometryBasics
+
+p1 = Point(3, 1)
+p2 = Point(1, 3);
+p3 = Point(4, 4);
+```
+
+Geometries can carry metadata:
+
+```@repl quickstart
+poi = meta(p1, city="Abuja", rainfall=1221.2)
+```
+
+Metadata is stored in a NamedTuple and can be retrieved as such:
+
+```@repl quickstart
+meta(poi)
+```
+
+Specific metadata attributes can be directly retrieved:
+
+```@repl quickstart
+poi.rainfall
+```
+
+To remove the metadata and keep only the geometry, use `metafree`:
+
+```@repl quickstart
+metafree(poi)
+```
+
+Geometries have predefined metatypes:
+
+```@repl quickstart
+multipoi = MultiPointMeta([p1], city="Abuja", rainfall=1221.2)
+```
+
+Connect the points with lines:
+
+```@repl quickstart
+l1 = Line(p1, p2)
+l2 = Line(p2, p3);
+```
+
+Connect the lines in a linestring:
+
+```@repl quickstart
+LineString([l1, l2])
+```
+
+Linestrings can also be constructed directly from points:
+
+```@repl quickstart
+LineString([p1, p2, p3])
+```
+
+The same goes for polygons:
+
+```@repl quickstart
+Polygon(Point{2, Int}[(3, 1), (4, 4), (2, 4), (1, 2), (3, 1)])
+```
+
+Create a rectangle placed at the origin with unit width and height:
+
+```@repl quickstart
+rect = Rect(Vec(0.0, 0.0), Vec(1.0, 1.0))
+```
+
+Decompose the rectangle into two triangular faces:
+
+```@repl quickstart
+rect_faces = decompose(TriangleFace{Int}, rect)
+```
+
+Decompose the rectangle into four vertices:
+
+```@repl quickstart
+rect_vertices = decompose(Point{2, Float64}, rect)
+```
+
+Combine the vertices and faces into a triangle mesh:
+
+```@repl quickstart
+mesh = Mesh(rect_vertices, rect_faces)
+```
+
+Use `GeometryBasics.mesh` to get a mesh directly from a geometry:
+
+```@repl quickstart
+mesh = GeometryBasics.mesh(rect)
+```

docs/src/index.md

@@ -2,10 +2,8 @@
 
 ## Types
 
-```@docs
-AbstractMesh
-Mesh
-```
+* [`AbstractMesh`](@ref)
+* [`Mesh`](@ref)
 
 ## How to create a mesh