Rehaul documentation build and add instructions (thofma#381)

docs/Build.jl

@@ -0,0 +1,88 @@
+#
+# This file is included by docs/make.jl and by a helper function
+# in src/Hecke.jl
+#
+module Build
+
+using Documenter, DocumenterMarkdown, DocumenterCitations
+
+pages = [
+         "index.md",
+         "Number fields" => [ "number_fields/intro.md",
+                              "number_fields/fields.md",
+                              "number_fields/elements.md",
+                              "number_fields/internal.md"],
+         "Function fields" => [ "function_fields/intro.md",
+                                "function_fields/basics.md",
+                                "function_fields/elements.md",
+                                "function_fields/internal.md",
+                                "function_fields/degree_localization.md"],
+         "Orders" => [ "orders/introduction.md",
+                       "orders/orders.md",
+                       "orders/elements.md",
+                       "orders/ideals.md",
+                       "orders/frac_ideals.md"
+                     ],
+         "abelian/introduction.md",
+         "class_fields/intro.md",
+         "sparse/intro.md",
+         "FacElem.md",
+         "examples.md",
+         "Developer" => [ "dev/test.md",
+                          "dev/documentation.md",
+                        ]
+        ]
+
+# Overwrite printing to make the header not full of redundant nonsense
+# Turns
+#   Hecke.Order - Method
+# into
+#   Order - Method
+
+# To remove the '-'
+# Documenter.Utilities.print_signature(io::IO, signature)        = print(io, signature)
+
+# To remove the "Method", "Type", "Module" use the following
+# Documenter.Utilities.doccat(b::Base.Docs.Binding, ::Type)  = ""
+# doccat(::Type)     = ""
+# doccat(::Module)   = ""
+
+# Remove the module prefix
+Base.print(io::IO, b::Base.Docs.Binding) = print(io, b.var)
+
+function make(Hecke::Module; strict::Bool = false,
+                             local_build::Bool = false,
+                             doctest::Bool = true,
+                             format::Symbol = :mkdocs)
+
+  # Load the bibliography
+  bib = CitationBibliography(joinpath(Hecke.pkgdir, "docs", "src", "Hecke.bib"), sorting = :nyt)
+
+  cd(joinpath(Hecke.pkgdir, "docs")) do
+    DocMeta.setdocmeta!(Hecke, :DocTestSetup, :(using Hecke); recursive = true)
+
+    if format == :html
+      makedocs(
+        bib,
+        format = Documenter.HTML(prettyurls = !local_build, collapselevel = 1),
+        doctest = doctest,
+        strict = strict,
+        modules = [Hecke],
+        sitename = "Hecke documentation",
+        pages = pages
+      )
+    elseif format == :mkdocs
+      makedocs(
+          bib,
+          doctest= doctest,
+          strict = strict,
+          modules = [Hecke],
+          format = Markdown(),
+      )
+    end
+  end
+end
+
+end # module Build
+
+using .Build

docs/make.jl

@@ -1,134 +1,135 @@
-using Documenter, DocumenterMarkdown, DocumenterCitations, Hecke, Nemo, AbstractAlgebra, Pkg
+using Documenter, Hecke
 
-@show Hecke.pkgdir
+include(normpath(joinpath(Hecke.pkgdir, "docs", "Build.jl")))
 
-# Overwrite printing to make the header not full of redundant nonsense
-# Turns
-#   Hecke.Order - Method
-# into
-#   Order - Method
+Build.make(Hecke; strict=false, local_build=false, doctest=true, format = :mkdocs)
 
-# To remove the '-'
-# Documenter.Utilities.print_signature(io::IO, signature)        = print(io, signature)
-
-# To remove the "Method", "Type", "Module" use the following
-# Documenter.Utilities.doccat(b::Base.Docs.Binding, ::Type)  = ""
-# doccat(::Type)     = ""
-# doccat(::Module)   = ""
-
-# Remove the module prefix
-Base.print(io::IO, b::Base.Docs.Binding) = print(io, b.var)
-
-DocMeta.setdocmeta!(Hecke, :DocTestSetup, :(using Hecke); recursive = true)
-
-bib = CitationBibliography(joinpath(Hecke.pkgdir, "docs", "src", "Hecke.bib"), sorting = :nyt)
-
-if Hecke.html_build[]
-  makedocs(
-      bib,
-      format = Documenter.HTML(prettyurls = !local_build),
-      doctest= true,
-      modules = [Hecke],
-      sitename = "Hecke documentation",
-      pages = [
-      "index.md",
-      "Number fields" => [ "number_fields/intro.md",
-                           "number_fields/fields.md",
-                           "number_fields/elements.md",
-                           "number_fields/internal.md"],
-      "Function fields" => [ "function_fields/intro.md",
-			     "function_fields/basics.md",
-			     "function_fields/elements.md",
-			     "function_fields/internal.md",
-			     "function_fields/degree_localization.md"],
-      "Orders" => [ "orders/introduction.md",
-                    "orders/orders.md",
-                    "orders/elements.md",
-                    "orders/ideals.md",
-                    "orders/frac_ideals.md"
-                  ],
-#      "Maximal Orders" => [ "MaximalOrders/Introduction.md",
-#                            "MaximalOrders/Creation.md",
-#                            "MaximalOrders/Elements.md",
-#                            "MaximalOrders/Ideals.md"
-#                          ],
-      "abelian/introduction.md",
-      "class_fields/intro.md",
-      "sparse/intro.md",
-      "FacElem.md",
-      "examples.md",
-      ]
-
-  )
-else
-  makedocs(
-      bib,
-      doctest= true,
-      modules = [Hecke],
-      format = Markdown(),
-  )
-
-  docsdir = joinpath(@__DIR__, "build/")
-
-  function _super_cool_example(f, overwrite = true)
-    inside = false
-    new_file = ""
-    collapsing = false
-    open(f) do file
-      for ln in eachline(file);
-        if startswith(ln, "<a id='Example")
-          continue
-        end
-        if startswith(ln, "#### Example")
-          if startswith(ln, "#### Example +")
-            collapsing = true
-          end
-          ln = ""
-          inside = true
-        end
-        if inside
-          if startswith(ln, "```julia-repl")
-            if collapsing
-              line = "??? note \"Example\"\n    ```julia"
-              collapsing = false
-            else
-              line = "!!! note \"Example\"\n    ```julia"
-            end
-          else
-            line = "    " * ln
-          end
-        else
-          line = ln;
-        end
-
-        if startswith(ln, "```") && !occursin("julia-repl", ln)
-          inside = false
-        end
-        new_file = new_file * "\n" * line
-      end
-    end
-    rm(f)
-    open(f, "w") do file
-      write(file, new_file)
-    end
-  end
-
-  for (root, dirs, files) in walkdir(docsdir)
-    for file in files
-      filename = joinpath(root, file) # path to files
-      #run(`sed -i 's/.*dash; \*Method.*/---/g' $filename`)
-      #run(`sed -i 's/.*dash; \*Type.*/---/g' $filename`)
-      #run(`sed -i 's/.*dash; \*Function.*/---/g' $filename`)
-      #run(`sed -i '/>source<\/a>/d' $filename`)
-      #run(`sed -i '/>\#<\/a>/d' $filename`)
-      _super_cool_example(filename)
-    end
-  end
-end
+## Overwrite printing to make the header not full of redundant nonsense
+## Turns
+##   Hecke.Order - Method
+## into
+##   Order - Method
+#
+## To remove the '-'
+## Documenter.Utilities.print_signature(io::IO, signature)        = print(io, signature)
+#
+## To remove the "Method", "Type", "Module" use the following
+## Documenter.Utilities.doccat(b::Base.Docs.Binding, ::Type)  = ""
+## doccat(::Type)     = ""
+## doccat(::Module)   = ""
+#
+## Remove the module prefix
+#Base.print(io::IO, b::Base.Docs.Binding) = print(io, b.var)
+#
+#DocMeta.setdocmeta!(Hecke, :DocTestSetup, :(using Hecke); recursive = true)
+#
+#
+#if Hecke.html_build[]
+#  makedocs(
+#      bib,
+#      format = Documenter.HTML(prettyurls = !local_build),
+#      doctest= true,
+#      modules = [Hecke],
+#      sitename = "Hecke documentation",
+#      pages = [
+#      "index.md",
+#      "Number fields" => [ "number_fields/intro.md",
+#                           "number_fields/fields.md",
+#                           "number_fields/elements.md",
+#                           "number_fields/internal.md"],
+#      "Function fields" => [ "function_fields/intro.md",
+#			     "function_fields/basics.md",
+#			     "function_fields/elements.md",
+#			     "function_fields/internal.md",
+#			     "function_fields/degree_localization.md"],
+#      "Orders" => [ "orders/introduction.md",
+#                    "orders/orders.md",
+#                    "orders/elements.md",
+#                    "orders/ideals.md",
+#                    "orders/frac_ideals.md"
+#                  ],
+#      "abelian/introduction.md",
+#      "class_fields/intro.md",
+#      "sparse/intro.md",
+#      "FacElem.md",
+#      "examples.md",
+#      ]
+#
+#  )
+#else
+#  makedocs(
+#      bib,
+#      doctest= true,
+#      modules = [Hecke],
+#      format = Markdown(),
+#  )
+#
+#  docsdir = joinpath(@__DIR__, "build/")
+#
+#  function _super_cool_example(f, overwrite = true)
+#    inside = false
+#    new_file = ""
+#    collapsing = false
+#    open(f) do file
+#      for ln in eachline(file);
+#        if startswith(ln, "<a id='Example")
+#          continue
+#        end
+#        if startswith(ln, "#### Example")
+#          if startswith(ln, "#### Example +")
+#            collapsing = true
+#          end
+#          ln = ""
+#          inside = true
+#        end
+#        if inside
+#          if startswith(ln, "```julia-repl")
+#            if collapsing
+#              line = "??? note \"Example\"\n    ```julia"
+#              collapsing = false
+#            else
+#              line = "!!! note \"Example\"\n    ```julia"
+#            end
+#          else
+#            line = "    " * ln
+#          end
+#        else
+#          line = ln;
+#        end
+#
+#        if startswith(ln, "```") && !occursin("julia-repl", ln)
+#          inside = false
+#        end
+#        new_file = new_file * "\n" * line
+#      end
+#    end
+#    rm(f)
+#    open(f, "w") do file
+#      write(file, new_file)
+#    end
+#  end
+#
+#  for (root, dirs, files) in walkdir(docsdir)
+#    for file in files
+#      filename = joinpath(root, file) # path to files
+#      #run(`sed -i 's/.*dash; \*Method.*/---/g' $filename`)
+#      #run(`sed -i 's/.*dash; \*Type.*/---/g' $filename`)
+#      #run(`sed -i 's/.*dash; \*Function.*/---/g' $filename`)
+#      #run(`sed -i '/>source<\/a>/d' $filename`)
+#      #run(`sed -i '/>\#<\/a>/d' $filename`)
+#      _super_cool_example(filename)
+#    end
+#  end
+#end
 
 deploydocs(
   repo = "github.com/thofma/Hecke.jl.git",
-  deps = Deps.pip("pymdown-extensions", "pygments", "mkdocs", "python-markdown-math", "mkdocs-material", "mkdocs-cinder"),
+  deps = Deps.pip("pymdown-extensions",
+                  "pygments",
+                  "mkdocs",
+                  "python-markdown-math",
+                  "mkdocs-material",
+                  "mkdocs-cinder"),
   target = "site",
   make = () -> run(`mkdocs build`),
 )

docs/mkdocs.yml

@@ -100,5 +100,6 @@ nav:
       - Misc: misc.md
     - Developer:
       - Testing: 'dev/test.md'
+      - Documentation: 'dev/documentation.md'
   - Examples: 'examples.md'
   - Source: 'https://www.github.com/thofma/Hecke.jl'

docs/src/number_fields/elements.md

@@ -43,9 +43,9 @@ julia> L([a, 1, 1//2])
 
 ```@docs
 quadratic_defect(a::NumFieldElem, p)
-hilbert_symbol(a::T, b::T, p::Union{NfAbsOrdIdl, NfRelOrdIdl}) where {T <: NumFieldElem}
+hilbert_symbol(a::nf_elem, b::nf_elem, p::Union{NfAbsOrdIdl, NfRelOrdIdl})
 representation_matrix(::NumFieldElem)
-basis_matrix(::Vector{<:NumFieldElem})
+basis_matrix(::Vector{nf_elem})
 coefficients(::SimpleNumFieldElem)
 coordinates(::NumFieldElem)
 absolute_coordinates(::NumFieldElem)