https://pantsbuild.org/ logo
#development
Title
# development
b

bitter-ability-32190

01/10/2022, 9:32 PM
There's a stray space on https://www.pantsbuild.org/docs/plugins-fmt-goal in
platform_mapping
in step 1 on the last entry in the leading whitespace
w

witty-crayon-22786

01/10/2022, 9:35 PM
thanks! in future, feel free to
Suggest an Edit
at the top right
i’ll go ahead and edit directly
b

bitter-ability-32190

01/10/2022, 9:37 PM
I did that once and was dissuaded. Perhaps it depends on the page/contents whether that button should be used or not
e

enough-analyst-54434

01/10/2022, 9:40 PM
It does. You're only dissuaded from anything in the "Reference" section on the home page - those 4 all all generated from code docstrings. For those, you edit the code.
🙌 1
Global Options, Goals, Subsystems, Targets
b

bitter-ability-32190

01/10/2022, 9:41 PM
OK that makes sense
w

witty-crayon-22786

01/10/2022, 9:43 PM
ah, yea: sorry for the confusion.
b

bitter-ability-32190

01/11/2022, 2:06 PM
Actually, why aren't the docs source in the repo?
e

enough-analyst-54434

01/11/2022, 2:16 PM
They used to be. The long and the short of it is everyone agreed over a long span of time the generated doc site that resulted was a problem. Over that same long span of time no one stepped up to do something about it. Finally Benjy or Eric or both did. In my mind action wins in a case like that, full stop. That said there were also reasons I can't remember for the choice. My guess was the bias was towards non-developer users (which doesn't actually make sense), or more accurately, developer users that found editing via a web UI more approachable / submitting PRs more burdensome.
In that spirit, the minimal step-up here would be to fix the generated portion of the docs to clearly header or footer or both how to edit those pages; ideally with a way to turn off the suggest edits web UI for those pages. I looked at the latter yesterday and found no way to do this per page in the readme.com docs yesterday, and like the events of the past, gave up at that point.
b

bitter-ability-32190

01/11/2022, 2:22 PM
So IIUC the doc site isn't generated from some file(s) like Markdown? And therefore couldn't be hosted in repo?
e

enough-analyst-54434

01/11/2022, 2:24 PM
The doc site is hand written using the web UI except for the 4 generated reference subsections discussed above. For more info you're probably best familiarizing yourself with readme.com docs. We have no fancy arrangements with them and are using the stock product.
👍 1
b

bitter-ability-32190

01/11/2022, 2:28 PM
Ah OK, then that makes complete sense
h

hundreds-father-404

01/13/2022, 6:07 PM
Yeah we really liked Readme.com compared to other options like readthedocs. Along the way, we realized the need for generated docs so Benjy wrote the
generate_docs.py
script to use the readme.com API