Should we add a message to reference mdx files saying they're auto-generated?

[davepagurek]

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.

[davepagurek]

If we do want to do this, the conversion to mdx happens here

p5.js-website/src/scripts/builders/reference.ts

Line 396 in ee34118

const convertDocsToMDX = async (

(and also in saveMdx() below.)

[ksen0]

@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?

[davepagurek]

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!"