Adopt ExDoc & Move Documentation In-Tree

[jessestimpson]

This PR uses ExDoc for docs generation and moves all documentation source into the main rebar3 repository.

The primary goal is to bring rebar3's documentation process in line with modern Erlang community standards, enhancing discoverability, familiarity, and contributor experience.

Demo

rebar3exdocdemo.stimpson.io

For demonstration purposes, I've hosted the combined rebar3 ExDocs at the location above. I'll keep them up and running for the lifetime of this PR.

Proposal

This PR proposes three major changes:

1. Move Documentation Source In-Tree: The source files for documentation (currently in the separate rebar3.org included directly in the rebar3 project.
2. Adopt ExDoc for Generation
3. Hosting: Create hexdocs.pm/rebar3

Motivation

1. Familiarity & Community Alignment

• Standardization: ExDoc is the standard documentation tool across the Erlang/Elixir ecosystem, used by OTP, Elixir, and the majority of popular libraries.
• Reduced Friction: By following this convention, new and experienced contributors alike can navigate and understand the documentation process much faster.

2. Enhanced Discoverability

• Expected Locations: A new user would likely look for documentation at erlang.org or HexDocs. Currently, the documentation is not hosted in either.

3. Facilitating Contribution

• Easy Local Generation: Contributors can now easily generate a complete, local version of the documentation with a simple command, viewing their changes before submitting. (And without npm 😄 )
• Higher-Quality PRs: A simpler local build process increases contributor comfort and naturally leads to more comprehensive, higher-quality documentation improvements.

4. Clear Public API Definition

• Convention-Driven Clarity: ExDoc's default conventions inherently clarify the public API. Any module that appears in the "Modules" section is considered public.
• Robust Plugins: This clear distinction will help developers building rebar3 plugins create more robust and stable integrations by knowing exactly which parts of rebar3's API they can safely rely on.

Progress

• Copy docs content from https://github.com/tsloughter/rebar3.org.git and rework as needed for ExDoc formatting and linking
• Add docs profile to rebar.config
• Generate docs with ./rebar3 as docs ex_doc --app rebar
• All content changes summarized in commit message
• Support for groups_for_extras
• Restrict module inclusion to public API only (i.e. -moduledoc false. where appropriate)

[tsloughter]

Love it!

[ferd]

I like it as well. I think we'd have to crystallize some of the approach chosen to be broadly compatible with the project (version support, dynamism supported).

Some of the key features of the main site are also the download links on the landing page which no longer exist here, but could certainly be unified a bit better.

I think this is worth pursuing.

[jessestimpson]

Thanks for the feedback. I'll update here with the next iteration, hopefully by the weekend.

For the record, I'm hoping we can get rebar_ex_doc plugin support for groups_for_extras to keep the correct docs organization. The current demo ignores the metadata from the _index.md files.

jelly-beam/rebar3_ex_doc#120

[jessestimpson]

Updates:

• Removed doc.config[.script]
• Doc content now in the source tree
• Adjusted formatting and linking to fit ExDoc spec. Unfortunately, review of these changes will be challenging since it's a copy from another repo. I suppose I should have committed the base files first to allow diffing between commits, but I didn't think of it until now.
• Updated demo page with latest
• Created checklist in main PR description with remaining items

[jessestimpson]

rebar3_ex_doc 0.2.31 added support for groups_for_extras, and I put the README urls back to rebar3.org.

Next I will continue with restricting visibility of modules to only those expected as part of the public API.

[jessestimpson]

@ferd @tsloughter This PR is ready for review. The latest is hosted at the same demo link.

Known issue: providers, provider, and any other public API module from the vendor dir aren't included in the docs. I wasn't able to find a config option in ExDoc to specify additional source dirs.

There will be some changes to be made after it's merged that have to be orchestrated. Please let me know how I can assist further.

1. Publishing the generated docs to hexdocs using a maintainer's account
2. Changes to rebar3.org web server to redirect to hexdocs
3. Removal of doc content from rebar3.org git repo?
4. Any GitHub actions that may exist?