Rewrite Developer's Manual

[hgluka]

Description

This is (the start of) a rewrite of documents/README.org, with changes based on the discussion from #3068.

Resolves #3068.

Discussion

I deleted several sections in the first commit. Let me know if I'm moving in the right direction, or if I need to bring some of the deleted parts back.

cc @jmercouris

Checklist:

Everything in this checklist is required for each PR. Please do not approve a PR that does not have all of these items.

• Git hygiene:
  • I have pulled from master before submitting this PR
  • There are no merge conflicts.
• I've added the new dependencies as:
  • ASDF dependencies,
  • Git submodules,

    cd /path/to/nyxt/checkout
    git submodule add https://gitlab.common-lisp.net/nyxt/py-configparser _build/py-configparser

  • and Guix dependencies.
• My code follows the style guidelines for Common Lisp code. See:
  • Norvig & Pitman's Tutorial on Good Lisp Programming Style (PDF)
  • Google Common Lisp Style Guide
• I have performed a self-review of my own code.
• My code has been reviewed by at least one peer. (The peer review to approve a PR counts. The reviewer must download and test the code.)
• Documentation:
  • All my code has docstrings and :documentations written in the aforementioned style. (It's OK to skip the docstring for really trivial parts.)
  • I have updated the existing documentation to match my changes.
  • I have commented my code in hard-to-understand areas.
  • I have updated the changelog.lisp with my changes if it's anything user-facing (new features, important bug fix, compatibility breakage).
    • Changelog update should be a separate commit.
  • I have added a migration.lisp entry for all compatibility-breaking changes.
  • (If this changes something about the features showcased on Nyxt website) I have these changes described in the new/existing article at Nyxt website or will notify one of maintainters to do so.
• Compilation and tests:
  • My changes generate no new warnings.
  • I have added tests that prove my fix is effective or that my feature works. (If possible.)
  • I ran the tests locally ((asdf:test-system :nyxt) and (asdf:test-system :nyxt/gi-gtk)) and they pass.

[aadcg]

Overall, it looks good to me!

I'm not sure if we should delete the section "Interacting with a compiled version of Nyxt". I think we could have a short subsection under "Development environment guide" that would include sections "SLIME" and "SLY/SLYNK". Ideally it should be really short (no need for two separate sections) since it's basically the same as soon as the reader establishes the correspondence between pairs Slime-Swank and Sly-Slynk.

What do you think @hgluka?

[hgluka]

I think you're right. That way, we give newcomers two options:

1. Set up Guix and SLY and run from source
2. Install (as explained in the Developer's installation guide) and use SLIME/SLY

Seems good to me.

EDIT: Plus, I wrote "If you wish to use other tools, refer to the rest of the manual below." in the Development environment guide, so it would be good to have a way to do that actually explained in "the rest of the manual below."

[aadcg]

@hgluka it seems that you're suggesting that the Swank/Slynk should come appear under section "Developer's installation guide". That makes even more sense, since that approach requires compiling Nyxt. Good observation.

[hgluka]

@aadcg Exactly. I added it at the end of the "Developer's installation guide" section.

[aadcg]

@hgluka I think it's almost ready. Please squash all commits to a single one, where you succinctly explain all changes to the document.

I've left 2 comments on hunks that are ought to be reverted, since it's just a change in terms of whitespace.

[aadcg]

Thanks @hgluka!