Add interactive HQMTool and testing

.github/workflows/DocPreviewCleanup.yml

@@ -0,0 +1,32 @@
+name: Doc Preview Cleanup
+
+on:
+ pull_request:
+ types: [closed]
+
+jobs:
+ doc-preview-cleanup:
+ # Do not run on forks to avoid authorization errors
+ # Source: https://github.community/t/have-github-action-only-run-on-master-repo-and-not-on-forks/140840/18
+ if: github.repository_owner == 'trixi-framework'
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout gh-pages branch
+ uses: actions/checkout@v2
+ with:
+ ref: gh-pages
+
+ - name: Delete preview and history
+ shell: bash
+ run: |
+ git config user.name "Documenter.jl"
+ git config user.email "[email protected]"
+ git rm -rf --ignore-unmatch "previews/PR$PRNUM"
+ git commit -m "delete preview" --allow-empty
+ git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+ env:
+ PRNUM: ${{ github.event.number }}
+
+ - name: Push changes
+ run: |
+ git push --force origin gh-pages-new:gh-pages

.gitignore

@@ -1,8 +1,12 @@
 **/Manifest.toml
 out*/
 docs/build
+docs/src/authors.md
 public/
 coverage/
 coverage_report/
 **/*.jl.*.cov
 .vscode/
+examples/*.tec
+examples/*.mesh
+*.png

AUTHORS.md

@@ -0,0 +1,24 @@
+# Authors
+
+HOHQMesh.jl is maintained by the
+[Trixi authors](https://github.com/trixi-framework/Trixi.jl/blob/main/AUTHORS.md).
+Its development is coordinated by the *principal developers* who are its main
+contributors and can be contacted in case of questions about HOHQMesh. In addition,
+there are *contributors* who have provided substantial additions or modifications.
+The [*HOHQMesh*](https://github.com/trixi-framework/HOHQMesh) mesh generator itself
+is developed by David A. Kopriva.
+
+## Principal Developers
+* [David A. Kopriva](https://www.math.fsu.edu/~kopriva/),
+ Florida State University, USA
+* [Andrew Winters](https://liu.se/en/employee/andwi94),
+ Linköping University, Sweden
+
+## Contributors
+The following people contributed major additions or modifications to HOHQMesh and
+are listed in alphabetical order:
+
+* David Kopriva
+* Hendrik Ranocha
+* Michael Schlottke-Lakemper
+* Andrew Winters

LICENSE.md

@@ -1,21 +1,21 @@
 MIT License
 
-Copyright (c) 2021-present Michael Schlottke-Lakemper
+Copyright (c) 2021-present David Kopriva, Andrew Winters, and Michael Schlottke-Lakemper
 
-Permission is hereby granted, free of charge, to any person obtaining a copy 
-of this software and associated documentation files (the "Software"), to deal 
-in the Software without restriction, including without limitation the rights 
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
-copies of the Software, and to permit persons to whom the Software is 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all 
+The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

Project.toml

@@ -5,7 +5,9 @@ version = "0.1.2-pre"
 
 [deps]
 HOHQMesh_jll = "1d5cbd98-5122-5a8a-bea1-c186d986ee7f"
+Requires = "ae029012-a4dd-5104-9daa-d747884805df"
 
 [compat]
 HOHQMesh_jll = "1.0"
+Requires = "1.1.3"
 julia = "1.6"

docs/make.jl

@@ -5,6 +5,13 @@ using HOHQMesh
 # Define module-wide setups such that the respective modules are available in doctests
 DocMeta.setdocmeta!(HOHQMesh, :DocTestSetup, :(using HOHQMesh); recursive=true)
 
+# Get Trixi root directory
+hohqmesh_root_dir = dirname(@__DIR__)
+
+# Copy list of authors to not need to synchronize it manually
+authors_text = read(joinpath(hohqmesh_root_dir, "AUTHORS.md"), String)
+write(joinpath(@__DIR__, "src", "authors.md"), authors_text)
+
 # Make documentation
 makedocs(
  # Specify modules for which docstrings should be shown
@@ -15,15 +22,33 @@ makedocs(
  format = Documenter.HTML(
  # Disable pretty URLs during manual testing
  prettyurls = get(ENV, "CI", nothing) == "true",
- # Explicitly add favicon as asset
- # assets = ["assets/favicon.ico"],
  # Set canonical URL to GitHub pages URL
  canonical = "https://trixi-framework.github.io/HOHQMesh.jl/stable"
  ),
  # Explicitly specify documentation structure
  pages = [
  "Home" => "index.md",
+ "Interactive mesh generation" => [
+ "interactive_overview.md",
+ "guided-tour.md",
+ "interactive-api.md",
+ "CheatSheet.md",
+ ],
+ "Tutorials" => [
+ "Overview" => joinpath("tutorials", "introduction.md"),
+ joinpath("tutorials", "straight_outer_boundary.md"),
+ joinpath("tutorials", "curved_outer_boundary.md"),
+ joinpath("tutorials", "spline_curves.md"),
+ joinpath("tutorials", "create_edit_curves.md"),
+ ],
+ "Advanced topics & developers" => [
+ "Development" => "development.md",
+ "GitHub & Git" => "github-git.md",
+ "Testing" => "testing.md",
+ ],
  "Reference" => "reference.md",
+ "Authors" => "authors.md",
+ "Contributing" => "contributing.md",
  "License" => "license.md"
  ],
  strict = true # to make the GitHub action fail when doctests fail, see https://github.com/neuropsychology/Psycho.jl/issues/34
@@ -32,5 +57,5 @@ makedocs(
 deploydocs(
  repo = "github.com/trixi-framework/HOHQMesh.jl",
  devbranch = "main",
- # push_preview = true
+ push_preview = true
 )

docs/src/CheatSheet.md

@@ -0,0 +1,97 @@
+# Commands Cheat Sheet
+
+This provides a quick reference for the syntax
+of the interactive construction of boundary curves, background grid, etc.
+When possible, the commands presented below give
+generic versions of the function calls, e.g., for creating a new curve or
+adding the curve to a boundary chain. The script
+`interactive_outer_boundary_generic.jl` in the `examples` folder
+constructs an identical example mesh as shown in the [Guided tour](@ref)
+using generic function calls.
+
+A thorough description of the functions can be found in the [API](@ref) section.
+
+The general workflow of the interactive mesh functionality within a REPL session is
+
+1. Create a project
+2. Add boundary curves
+3. Add a background grid
+4. Add manual refinement (if desired)
+5. Generate mesh
+
+## Project
+
+```
+ p = newProject(<projectName>, <folder>)
+```
+
+## [Plotting](@id cs-plotting)
+
+```
+ plotProject!(p, options)
+ updatePlot!(p, options)
+```
+
+The `options` are any sum of `MODEL`, `GRID`, `REFINEMENTS`, and `MESH`.
+## Curves
+
+```
+ c = new(name, startLocation [x,y,z],endLocation [x,y,z]) *Straight Line*
+ c = new(name,center [x,y,z],radius, startAngle, endAngle) *Circular Arc*
+ c = new(name, xEqn, yEqn, zEqn) *Parametric equation*
+ c = new(name, dataFile) *Spline with data from a file*
+ c = new(name, nKnots, knotsMatrix) *Spline with given knot values*
+```
+
+Shown here is the use of the function `new`, which is a shortcut to the full functions, e.g. `newCircularArcCurve`, etc. which have the same arguments.
+
+## [Manual Refinement](@id cs-manual-refinement)
+
+```
+ r = newRefinementCenter(name, center, gridSize, radius)
+ r = newRefinementLine(name, type, startPoint, endPoint, gridSize, width)
+```
+
+## Adding to a Project
+
+```
+ add!(p, c) *Add outer boundary curve*
+ add!(p, c, <InnerBoundaryName>) *Add curve to an inner boundary*
+ add!(p, r) *Add refinement region*
+
+ addBackgroundGrid!(p, [top, left, bottom, right], [nX, nY, nZ]) *No outer boundary*
+ addBackgroundGrid!(p, [dx, dy, dz]) *If an outer boundary is present*
+```
+Shown here is the use of the function `add!`, which is a shortcut to the full functions, e.g. `addOuterBoundaryCurve`, etc. which have the same arguments.
+
+## Accessing items
+
+```
+ crv = getCurve(p, curveName) *Get a curve in the outer boundary*
+ crv = getCurve(p, curveName, boundaryName) *Get a curve in an inner boundary*
+ indx, chain = getChain(p, boundaryName) *Get a complete inner boundary curve*
+ r = getRefinementRegion(p, name)
+```
+
+## Removing from Project
+
+```
+ removeOuterboundary!(p) *Entire outer boundary curve*
+ removeInnerBoundary!(p, innerBoundaryName) *Entire inner boundary curve*
+ remove!(p, name) *Curve in outer boundary*
+ remove!(p, name, innerBoundaryName) *Curve in inner boundary*
+ removeRefinementRegion!(p, name)
+```
+
+## Editing items
+
+All items have set/get methods to edit them. Most actions have `undo()` and `redo()`.
+To find out what the next undo/redo actions are, use `undoActionName()` and `redoActionName()`
+to print them to the screen.
+
+## Meshing
+
+```
+ generate_mesh(p)
+ remove_mesh!(p)
+```

docs/src/contributing.md

@@ -0,0 +1,54 @@
+# Contributing
+
+HOHQMesh.jl is an open-source project and we are very happy to accept contributions
+from the community. Please feel free to open issues or submit patches (preferably
+as merge requests) any time. For planned larger contributions, it is often
+beneficial to get in contact with one of the principal developers first (see
+[Authors](@ref)).
+
+HOHQMesh.jl and its contributions are licensed under the MIT license (see
+[License](@ref)). As a contributor, you certify that all your
+contributions are in conformance with the *Developer Certificate of Origin
+(Version 1.1)*, which is reproduced below.
+
+## Developer Certificate of Origin (Version 1.1)
+The following text was taken from
+[https://developercertificate.org](https://developercertificate.org):
+
+ Developer Certificate of Origin
+ Version 1.1
+
+ Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+ 1 Letterman Drive
+ Suite D4700
+ San Francisco, CA, 94129
+
+ Everyone is permitted to copy and distribute verbatim copies of this
+ license document, but changing it is not allowed.
+
+
+ Developer's Certificate of Origin 1.1
+
+ By making a contribution to this project, I certify that:
+
+ (a) The contribution was created in whole or in part by me and I
+ have the right to submit it under the open source license
+ indicated in the file; or
+
+ (b) The contribution is based upon previous work that, to the best
+ of my knowledge, is covered under an appropriate open source
+ license and I have the right under that license to submit that
+ work with modifications, whether created in whole or in part
+ by me, under the same open source license (unless I am
+ permitted to submit under a different license), as indicated
+ in the file; or
+
+ (c) The contribution was provided directly to me by some other
+ person who certified (a), (b) or (c) and I have not modified
+ it.
+
+ (d) I understand and agree that this project and the contribution
+ are public and that a record of the contribution (including all
+ personal information I submit with it, including my sign-off) is
+ maintained indefinitely and may be redistributed consistent with
+ this project or the open source license(s) involved.

docs/src/development.md

@@ -0,0 +1,67 @@
+# Development
+
+## Text editors
+When writing code, the choice of text editor can have a significant impact on
+productivity and developer satisfaction. While using the default text editor
+of the operating system has its own benefits (specifically the lack of an explicit
+installation procure), usually it makes sense to switch to a more
+programming-friendly tool. In the following, a few of the many options are
+listed and discussed:
+
+### VS Code
+[Visual Studio Code](https://code.visualstudio.com/) is a modern open source
+editor with [good support for Julia](https://github.com/julia-vscode/julia-vscode).
+While [Juno](#Juno) had some better support in the past, the developers of Juno
+and the Julia VS Code plugin are joining forces and concentrating on VS Code
+since support of Atom has been suspended. Basically, all comments on [Juno](#Juno)
+below also apply to VS Code.
+
+### Juno
+If you are new to programming or do not have a preference for a text editor
+yet, [Juno](https://junolab.org) is a good choice for developing Julia code.
+It is based on *Atom*, a sophisticated and widely used editor for software
+developers, and is enhanced with several Julia-specific features. Furthermore
+and especially helpful for novice programmers, it has a MATLAB-like
+appearance with easy and interactive access to the current variables, the
+help system, and a debugger.
+
+### Vim or Emacs
+Vim and Emacs are both very popular editors that work great with Julia. One
+of their advantages is that they are text editors without a GUI and as such
+are available for almost any operating system. They also are preinstalled on
+virtually all Unix-like systems. However, Vim and Emacs come with their own,
+steep learning curve if they have never been used before. Therefore, if in doubt, it
+is probably easier to get started with a classic GUI-based text editor (like
+Juno). If you decide to use Vim or Emacs, make sure that you install the
+corresponding Vim plugin
+[julia-vim](https://github.com/JuliaEditorSupport/julia-vim) or Emacs major
+mode [julia-emacs](https://github.com/JuliaEditorSupport/julia-emacs).
+
+
+
+## Releasing a new version of HOHQMesh
+
+- Check whether everything is okay, tests pass etc.
+- Set the new version number in `Project.toml` according to the Julian version of semver.
+ Commit and push.
+- Comment `@JuliaRegistrator register` on the commit setting the version number.
+- `JuliaRegistrator` will create a PR with the new version in the General registry.
+ Wait for it to be merged.
+- Increment the version number in `Project.toml` again with suffix `-pre`. For example,
+ if you have released version `v0.2.0`, use `v0.2.1-pre` as new version number.
+
+
+
+## Preview the documentation
+
+You can build the documentation of HOHQMesh.jl locally by running
+```bash
+julia --project=docs -e 'using Pkg; Pkg.instantiate(); include("docs/make.jl")'
+```
+from the HOHQMesh.jl main directory. Then, you can look at the html files generated in
+`docs/build`.
+For PRs triggered from branches inside the HOHQMesh.jl main repository previews of
+the new documentation are generated at `https://trixi-framework.github.io/HOHQMesh.jl/previews/PRXXX`,
+where `XXX` is the number of the PR.
+Note, this does not work for PRs from forks for security reasons (since anyone could otherwise push
+arbitrary stuff, including malicious code).