#159, #72 - Restructuring of docs

[schillic]

Closes #159. Workaround for #72.

• Add missing documentation.
• Add workaround for Fix 'docstrings potentially missing' warnings #72. The only warnings that are still printed are the ones for functions only defined in presence of Polyhedra.jl. Should we remove them as well?
• Have interface documentation at one place and link to it (Remove duplicate inherited functions from docs #159).
  • There are still some problems with Documenter in case of multiple methods. As a workaround, I omit the hyperlinks when there are conflicts.
  • To elaborate:
    • default values (e.g., p::Real=Inf): This simply does not work.
    • type parameters: On the lowest interface level we can use an instantiation of the type parameters, like an_element(::LazySet{Real}); for this case one can also create a hyperlink reference. On higher (interface/type) levels, one has to use the where syntax in order to use the correct method; for this case there are no hyperlinks.
• Remove duplicate documentation for concrete types.
  • See above (where syntax).
  • I did not find a way to make the array function for array types (probably due to nested type parameters) and the functions with default values (norm/radius/diameter) work.
• Check that each implementation occurs in the docs.
• Check that workaround for Fix 'docstrings potentially missing' warnings #72 is not created by default.
  • The page is not created, but the warnings are absorbed.
• Fix broken doctests.
  • I have never seen those broken ones so far. Apparently up to now the doctests never executed for VPolytope.jl and plot_recipes.jl, probably because the documentation was not used before.

[mforets]

just a comment: many people do not add a docstring to module LazySets, in which case this @docs is not needed -- by default julia will print the README.md of the package. i like this idea because it has some more info such as links to online documentation that our current Main module for LazySets.jl -- a Julia package for calculus with convex sets.

[schillic]

Okay, then I vote for removing this @docs. Otherwise we get a warning.

[mforets]

okay. can you do that?

[schillic]

done

[mforets]

what is the purpose of the file methods_fix.md?

[schillic]

If you add it, all the Documenter warnings about missing documentation are gone. Of course this is dangerous, so I commented this line. But it can help find missing docs at least for new function/type names quickly. In particular, I finally managed to exclude the warnings about apply_recipe!

[mforets]

hooray 🙌

most if not all of these functions with several methods should be documented, such as constraints_list. why does Documenter complain? since we include some (maybe not all) the variations of constraints_list in the docs.

[schillic]

No, the reason is described in #72. Documenter just does not recognize methods with default values or where syntax. Currently there is just no other way than manually searching for those docs. That is why I said that it is dangerous 😟

[mforets]

Titanic changeset, thanks for fixing!! 😄

here i only get:

 > checking for missing docstrings.
 !! 6 docstrings potentially missing:

    LazySets.cartesian_product :: Tuple{LazySets.VPolytope,LazySets.VPolytope}
    LazySets.cartesian_product :: Tuple{LazySets.HPolytope,LazySets.HPolytope}
    Polyhedra.polyhedron :: Union{Tuple{LazySets.VPolytope{N},Any}, Tuple{LazySets.VPolytope{N}}, Tuple{N}} where N
    Polyhedra.polyhedron :: Union{Tuple{LazySets.HPolytope{N},Any}, Tuple{LazySets.HPolytope{N}}, Tuple{N}} where N
    Base.intersect :: Union{Tuple{LazySets.VPolytope{N},LazySets.VPolytope{N}}, Tuple{N}} where N<:Real
    Base.intersect :: Union{Tuple{LazySets.HPolytope{N},LazySets.HPolytope{N}}, Tuple{N}} where N<:Real

[schillic]

Yes, these are only there with Polyhedra.
It is really cheating here. I just define a file that absorbs all other warnings. I am really not sure if this is a good idea or not. At least we can spot problems with new functions again. To me the previous state was at least as useless...