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)
• Mermaid diagrams (e.g. Dependencies Fetching Order)

[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.

[ferd]

This sigil usage is generally supported starting in OTP-27, which means it is not necessarily usable for OTP-26, which is still currently supported.

[jessestimpson]

Ah yes, good point. I will make this change

[ferd]

This works and I'm not opposed to it. I think this method omits the rest of the Rebar3 config when working on the project, which may drop some settings. Was this on purpose because they might clash?

If it wasn't on purpose, then one option here would have been to use profiles for this whole section within the default rebar.config file, and then allow calling ./rebar3 as docs ex_doc. This would require unscripting the stuff in doc.config.script though, which would be way too much work for a demo I imagine, but might be worth it in the end if we go for full support.

[jessestimpson]

I did it with doc.config[.script] on purpose for the first draft to demonstrate the blast radius of the change. Specifically, that the ex_doc config should be expected to have no impact on the rest of the project, to alleviate concerns about circular dependencies. I think we're on the same page here, so this is no longer a goal for the PR. 👍

I can continue the effort by exploring what it looks like in a merged rebar.config and without the script. However, without the script I think this will mean listing all markdown files explicitly in the rebar.config. I'll make it so and we can see how unmanageable that list looks. I don't mind doing multiple iterations to get it right.

[ferd]

Yeah I don't mind the file being distinct, the main concern is whether we'll require some duplication of config file values at some point. If we can survive without it, that's not a big deal.

[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

[ferd]

I think long term we'll want to keep things on rebar3.org, but if necessary just proxy/redirect to hex.pm/rehost there. Keeping the domain and links that have been indexed and used for years working would be good.