processing
Should we add a message to reference mdx files saying they're auto-generated?
Topic
It's a very common mistake for newcomers to this repo to try to edit a reference mdx file -- editing them does work, but they will get overwritten in the next release because the p5.js repo is the source of truth for (English) reference items.
Maybe we could add a comment to the top of each mdx file saying that it's auto generated? Ideally also with a link to where in the p5 repo it came from, similar to the link we put at the bottom of reference pages? This should only exist in the English ones, since the translations do actually live in this repo.
If we do want to do this, the conversion to mdx happens here https://github.com/processing/p5.js-website/blob/ee34118dd1a771da67df44ca5c7faaaa18703857/src/scripts/builders/reference.ts#L396 (and also in saveMdx() below.)
@davepagurek I agree, this is a good idea.
Practically, would it mean appending a comment (eg /* This file is auto-generated; to update the reference or fix typos, please check the inline documentation in [LINK] */) to each .mdx file when they are generated (and therefore only affecting files in en?) Would it break the astro parsing to put such a comment at the top of the file where it's visible BEFORE the person starts editing?
What do you think about updating the phrasing of the text at the bottom of each reference page to explicitly state: that reference pages are auto-generated?
Everything between the two --- lines is yaml, which supports comments starting with a #, so it would get ignored if we put it in like:
---
# This file is auto-generated; to update the reference or fix typos, please check the inline documentation in [LINK]
title: abs
module: Math
submodule: Calculation
file: src/math/calculation.js
description: >
<p>Calculates the absolute value of a number.</p>
line: 10
isConstructor: false
itemtype: method
class: p5
params:
- name: 'n'
description: |
<p>number to compute.</p>
type: Number
return:
description: absolute value of given number.
type: Number
chainable: false
---
# abs
What do you think about updating the phrasing of the text at the bottom of each reference page to explicitly state: that reference pages are auto-generated?
Sounds good to me, maybe: "This page is generated from the comments in [LINK]. Feel free to edit it and submit a pull request!"
@davepagurek sir i have added the comment on the start of every mdx english files. kindly check my pr.
Hi @Swapnil-6161 ! Looks like this issue has already been assigned to another contributor. Please note that in our contributor guidelines we ask that PRs are not made while someone is already working. Thanks for understanding!
Hi @krishna4040 are you working on this? No worries if you need time, just checking in!
(@13DATA was that your PR from a different account? In any case, let's see if this is being worked on and if not then it will be possible to reassign. Thanks for your patience!)
Hi @krishna4040, I hope you’re doing well! I wanted to check in and see if you’re still working on this issue. Please let me know if there’s anything we can assist you in resolving it. Thanks so much :)
@ksen0 @perminder-17 @krishna4040 Any updates on this? If not I'm available to work on it!
@adi-ray apologies that I missed this notification! If you want to work on this, go ahead - please write here to confirm so it's clear to anyone else who checks.