New contributing Guidelines add friction (documentation)

[telenieko]

Hi,

While working on #158 then #165 I noticed has been some developer friction added while contributing, mainly: contributing documentation is not straightforward.

One example is d295e4b, I added a paragraph to the documentation (see 13790a9) but the resulting .info file is much different. Probably because of some variable setup differently somewhere.

There should be a way to:

1. Render all documents at once (ie: make docs) so you can see if your changes had side effects (backlinks, etc)
2. Provide all necessary configuration, ie: in some "setup" orgfile included from all others that ensures indentation, etc is the same regardless of local setup
3. Setup a pre-commit hook that prevents commiting changes to documentation without make docs
4. A Github Action should make docs and see that the result matches what is being committed, otherwise fail

I say make docs because everybody understands what it means, not that I am endorsing Makefile in anyway :)

Maybe a docs/_bootstrap.org file could be introduced that has all the necessary setup and is included from the other documents. It may also have a couple babel blocks with a very basic build-all-docs function, etc. That would ensure that a) all variables are consistent regardless of local environment; b) it is straightforward to build all docs. Not sure if that would work though :|

[jeffbowman]

While working on #158 then #165 I noticed has been some developer friction added while contributing, mainly: contributing documentation is not straightforward.

This is unfortunate. I tried to provide enough guidance while empowering developers to put their own ideas together in the documentation. Perhaps we also need to improve the instructions in docs/CONTRIBUTING.org so it becomes more straight forward. Maybe also a blurb in the README.org in the "Contributing" section to help make things more straightforward.

One example is d295e4b, I added a paragraph to the documentation (see 13790a9) but the resulting .info file is much different. Probably because of some variable setup differently somewhere.

The info file will be different each time as it is a generated file. I don't generally pay much attention to it in terms of how the code looks inside the file, however, I do load it in Emacs to make sure it still looks good and is reasonably consistent when viewed in Emacs. I guess I hadn't noticed there were differences in formatting. I would indeed like to see the documentation (read: the info file) look as consistent as possible.

I like your ideas on configuring a "make docs" concept to consistently generate the info file. I'm looking forward to an implementation of your thoughts.

[jvdydev]

I actually use a simple elisp script with a Makefile and the compile command (running with emacs -Q --script to get a clean environment).
If there is interest, I can put something together, unless someone else is still working on this.

[jeffbowman]

No one is working on this as far as I know. I generate the info file and load it manually to check it, then either edit the org file and try again, or push the commit. So, go for it if ya want 🤓

[jvdydev]

I don't think it necessarily fixes all issues described, notably if the developer configuration somehow messes with org-mode files (e.g. formatting arbitrary parts automatically), that is hard to make align for everyone.

From my testing with the script, exporting in a clean Emacs session already removes a lot of "false diffs" in the generated info file.
I'll also see if I can make it an interactive command on its own without requiring make (and providing both solutions alongside docs).

[jeffbowman]

I don't think it necessarily fixes all issues described, notably if the developer configuration somehow messes with org-mode files (e.g. formatting arbitrary parts automatically), that is hard to make align for everyone.

Ye... It's a bit tough without a linter and formatter (Go anyone?) to ensure some level of consistency within the file and ignore configuration from a user. The emacs -Q --script thing gets reasonably close though... I've used that approach for somethings as well, with positive results.

I'll also see if I can make it an interactive command on its own without requiring make (and providing both solutions alongside docs)

That would be cool, I wonder if maybe that just sits in the CONTRIBUTING.org file as a code snippet that someone can just C-c C-c on and then magic? The only real issue with an external script thing is launching it in all the different platforms (Linux (easy, sh for the win), Microsoft Windows (ermm... less easy, maybe powershell?), MacOS (easy again, sh for the win)

[jvdydev]

ye, I was thinking of having the export and interactive functions defined in a file (e.g. crafted-docs.el) and then simply load that:

(load "/path/to/crafted-emacs/docs/crafted-docs.el")
;; if using crafted-emacs to develop crafted-emacs, could also be
(load (expand-file-name "docs/crafted-docs.el" crafted-emacs-home))
;; if it sits in the CONTRIBUTING.org, maybe just
(load (expand-file-name "crafted-docs.el"))

That would expose the interactive functions which themselves launch another emacs instance.

As for the script running, my current plan is:

• provide a Makefile for use with compile command (requires make)
• provide an interactive function, running the script with a new Emacs (emacs -Q --script ...)

The Makefile approach has the advantage of not re-building the file if the org files haven't changed (and people who use it probably have a keybinding for compile already).

The interactive function has no external dependencies (just Emacs in PATH).
Using just the shell-command* family of functions (or start-/create-process) should work on all platforms.
I'll check on Windows, but I'm pretty sure Emacs on Windows still uses the the - and -- prefixes (instead of Windows' style /).

The only requirement for both currently is Emacs in PATH which I think is reasonable (dependencies would be documented in CONTRIBUTING.org)?

[jvdydev]

After some more testing, I can confirm Emacs on Windows should work if Emacs is on PATH (and can build the documentation manually).
I also ended up using make-process directly to have it behave more naturally and give feedback (success/error) in the echo-area (similar to compile).

I'll put together some docs for it over the next few days and make a PR.

[jeffbowman]

Can this be closed @jvdydev given #306 and #307?

[jvdydev]

I guess so.
I originally kept it open because of the automated rebuild of docs, but I think we can move that into a new Issue for discussion on stuff like the criteria to kick off CI etc.

[jeffbowman]

Ok, we can keep it open if that makes sense. My thought was we seem to have several related issues and when we get to the point of closing them it's a lot of loose ends to track down.