Implement mdBook-Based Documentation for autofirma-nix

[nilp0inter]

Summary

The autofirma-nix project has grown in scope and complexity, making our current README quite cluttered. To improve the user experience and maintainability, we should create a dedicated documentation site using mdBook—similar to what stylix does. This new documentation will be published via GitHub Pages, with an automated workflow to keep it up to date.

Why This Is Needed

• Easier Navigation: A documentation site will be more structured than a single README file.
• Better Maintenance: We can split the content into separate chapters/pages, making updates simpler and less error-prone.
• User Clarity: New users will have clear, step-by-step instructions on how to install and configure AutoFirma under NixOS and Home Manager.

Proposed Approach

1. Set Up mdBook

   • Initialize a new docs folder (or book folder, naming is flexible) with an mdBook configuration.
   • Add a base SUMMARY.md to outline the structure (e.g., Installation, Configuration, Known Issues, FAQ).

2. Draft the Content

   • Port existing README sections into separate md files.
   • Create additional sections or pages as needed (e.g., advanced configuration, troubleshooting, etc.).
   • Keep the README minimal, linking out to the new documentation for detailed instructions.

3. Automate Publishing via GitHub Pages

   • Set up a GitHub Actions workflow to build the mdBook.
   • Deploy the built book to a gh-pages branch.
   • Configure the repository settings to serve from that branch or a /docs folder.

4. Improve Navigation & UX

   • Enable mdBook’s built-in search functionality.
   • Ensure the documentation is well-structured for easy reference.

5. Add Versioning (Future Consideration)

   • Potentially keep multiple versions of the documentation for different releases or branches if needed.

Tasks

• Initialize mdBook within a docs (or book) folder.
• Draft the documentation structure in SUMMARY.md.
• Migrate existing README sections (installation, usage, etc.) into individual chapters.
• Add a GitHub Actions workflow to build and deploy the documentation to GitHub Pages.
• Test the examples from the documentation are working.
• Verify that there is no lost of information. All valuable info from the current README is in the docs.
• Rewrite the README. It should contain a minimal project description. And a minimal working example with recommended settings.
• Link the main README and GitHub project description to the new documentation portal.

Additional Notes

• We can take inspiration from the stylix documentation repository structure.
• Once merged, this should reduce confusion for new users and keep the project more maintainable.

---

If anyone has ideas for organization, content, or improvements to the structure, please comment below. Let’s build a user-friendly documentation and keep autofirma-nix growing!

[nilp0inter]

A first stab at this is in the branch main, under docs. The render version can be read here.

/cc: @panchoh & @CesarGallego for review

[panchoh]

A first stab at this is in the branch main, under docs. The render version can be read here.

/cc: @panchoh & @CesarGallego for review

Nice!!!

At first glance, I’d suggest using sentence case instead of title case, as it is used (almost fully consistenly) in the stylix guide.
This would provide a lighter finish and, on top of that, would allow titles such as:

Home-Manager Module

to be rendered as:

Home Manager module

(Note that Home Manager as a project is spelled without the hyphen).

With title case, it would be rendered as:

Home Manager Module

which seems less clear to me since it detracts from the fact that Home Manager is a proper noun.

I’ve also noticed that in the options, the default values that have the with applied configuration litany, are backtick-quoted, possibly to distinguish the values from the litany, since they are rendered in the same font, but I wonder if it would be possible/desirable to render them like this:

some.foo.value (with applied configuration).

Finally, I noticed that on the troubleshooting section, on one line the tilde is used to refer to the home directory, and on the other, $HOME is used instead. I’d suggest using ~ on both, for consistency and simplicity.

I’ve yet to read the whole documentation thoroughly, but I thought that sending these your way early would be beneficial.

Awesome job, @nilp0inter !

[nilp0inter]

At first glance, I’d suggest using sentence case instead of title case, as it is used (almost fully consistenly) in the stylix guide. This would provide a lighter finish and, on top of that, would allow titles such as:

Home-Manager Module

to be rendered as:

Home Manager module

Done!

I’ve also noticed that in the options, the default values that have the with applied configuration litany, are backtick-quoted, possibly to distinguish the values from the litany, since they are rendered in the same font, but I wonder if it would be possible/desirable to render them like this:

some.foo.value (with applied configuration).

Nothing we can do about that, unfortunately.

Finally, I noticed that on the troubleshooting section, on one line the tilde is used to refer to the home directory, and on the other, $HOME is used instead. I’d suggest using ~ on both, for consistency and simplicity.

Noted. I am not changing that already because I suspect we'll be changing the whole section. The ChatGPT rewrite took a higher than expected toll on the content. :(

I’ve yet to read the whole documentation thoroughly, [..]

Me too 👯

Thank you for the review!

[panchoh]

I've reviewed the rest of the doc, and looks to me it’s ready for prime time!

[nilp0inter]

I've reviewed the rest of the doc, and looks to me it’s ready for prime time!

I think some examples are not working. We should test them before publication. Did you, by any chance, try them?

[panchoh]

I think some examples are not working. We should test them before publication. Did you, by any chance, try them?

Ah, no, I didn't.

[panchoh]

Reviewing that README was injected to the mdDoc sources.

Save for the following, all info has been preserved (not taking into account the possibly broken code examples):

The information on these paragraphs has gone into oblivion:

---

The integration of AutoFirma in Home Manager enables the autofirma command for
signing PDF documents and configures the Firefox browser (if enabled through
programs.firefox.enable) to use AutoFirma on websites that require it.

Additionally, you can enable DNIe integration, including NFC-based DNIe from an
Android mobile via DNIeRemote.

@nilp0inter, how do you want to proceed?

[nilp0inter]

Thanks, @panchoh! Please don't hesitate to commit the missing bits directly where you see fit.