Closed colemanw closed 9 months ago
@artfulrobot thanks, added.
That's all good except that the docs page doesn't include the detailed information for cv dl
or git clone
Would be helpful not to loose that.
Yeah I think that page could do with an update, but updating one place makes more sense than updating (or rather, not updating) hundreds of extensions.
@coleman looks good to me, thanks.
Deja vu: #166
tldr: To replace with these with better docs, we actually need the better docs...
(@colemanw) Installation instructions can be centralized and don't need to be copied into every extension's readme file...
(@artfulrobot) updating one place makes more sense than updating [than many]...
Completely agree. A centralized document can ultimately be better (more thorough/more complete/more thoughtfully edited).
The catch is that nobody on this thread (or the MM thread) has actually updated the docs... or even suggested that they would update them. That was where #166 fizzled out, too.
Perhaps the reason why no one has updated the generic docs is... it's a little fiddly. The commands are simple... if you know a couple variables. But you have to know the variables and plug them in. Depending on goals, you're looking at some subset of these questions:
So, actually, documenting this stuff is not as simple as waiving a hand (idiom).
As I see it, the options are:
The README links to dynamic documentation. Somebody actually works on that. (If an ext needs bespoke instructions, the author adds them on their own.)
For example, the README might link to a URL like:
https://download.civicrm.org/ext/MY_KEY?repo=MY_GIT
The page shows dynamic instructions with a few widgets, and it fills-in some fiddly bits.
In the interests of pushing forward, here's an example of dynamic instructions: https://jsfiddle.net/kdh6wrxp/1/ But that's only a start.
I do think (2) and (3) are better than (1) -- they'll ultimately produce more informative+maintainable instructions.
What I can't determine is the subtext. Are you (@colemanw or @artfulrobot) implying a real intent to update the docs yourself? Or are you soliciting for someone else (like me) to do the main work? (Not a trick question...)
Here you go: rewrite of extensions page: https://lab.civicrm.org/documentation/docs/sysadmin/-/merge_requests/375
@totten let's merge this!
civibot, test this please
civibot, test this please
civibot, test this please
There was an early test fail that was relevant, but I think that the latest one is just HTTPD flakiness.
Removes a bunch of boilerplate that clutters up every extension's readme file.
See https://chat.civicrm.org/civicrm/pl/5z13tkz8o7bypxrp8cis4xec7e
I think the aspiration of this boilerplate is good, but in practice: