Documentation improvements

[rustkas]

• dispatch_compiler.erl

  • Replace unnesecarylly html Character Entity < to <<.
  • Expanded the description of functions by -spec tag and EDoc tags.
  • Simplify -spec description.

• EDoc

  • Tune css stylesheet.

• GNUmakefile

  • Add documentation targets for generation public and private documenation.

• rebar.config

  • Add documentation generation and testing profiles.
  • Add option to generate public and private documentation.

• .gitignore

  • Add .gitignore option for generated documentation.

• test/dispatch_compiler_basic_SUITE.erl

  • Fix "Warning: export_all"

[mworrell]

It seems that the newest rebar3 does not support OTP 21 anymore, making the test fail.

Maybe we can remove the 21 test and add 24?
In Zotonic 1.x we only support 22.3 and later.

[rustkas]

It seems that the newest rebar3 does not support OTP 21 anymore, making the test fail.

Maybe we can remove the 21 test and add 24? In Zotonic 1.x we only support 22.3 and later.

Yes. You are right. I add modification to .github/workflows/test.yml. It should be worked.

[mmzeeman]

Looks good to me.

Nice that there is some work done on the documentation. Now that they are more readable, they should probably be pushed to hex as well.

[rustkas]

Looks good to me.

Nice that there is some work done on the documentation. Now that they are more readable, they should probably be pushed to hex as well.

Yes, Maas. You are right. I with Marc already have merged all of this using branch based on this one. It would be nice to merge this branch too in a way to save all that description related to this changes (saving this description for the history of changes.). I hope you can do it as good as possible.

I usually add documentation and updates to my hex.pm area in this way:

$ rebar3 do hex cut -i patch
$ rebar3 do hex publish --yes, hex docs

[mworrell]

And merged :-)

[mmzeeman]

Nice... For hex it is probably just a matter of building the documentation on the machine you push the hex package from.

[mworrell]

I have released 1.1.0

[mworrell]

See https://hex.pm/packages/dispatch_compiler

[mmzeeman]

This is going to look like something real.. \o/...

PS. @rustkas I used the same setup you provided for the type specs and doc strings in my educkdb package. (https://hexdocs.pm/educkdb/). So thanks a lot.

[rustkas]

Publishing documentation on hex.pm rebar3 projects has nuances which described on rebar3_publish. To comply with all conventions, it is necessary to follow his recommendations.

I have already encountered some peculiarities of work when publishing documentation for Erlang libraries that I posted under my account.

To do this I just add this to the rebar.config file:

{plugins, [rebar3_hex]}.

{edoc_opts, [
  {doclet, edoc_doclet_chunks},
  {layout, edoc_layout_chunks},
  {dir, "doc"}]}.

I noticed that the configuration files of the Zotonic projects that I have already met has not yet had that settings.