Contribution and doc build guidelines

[rhagenson]

trafficstars

Will close #1829 when merged.

Had to use a bit of sed to insert a "fake" index page in the correct place.

Improvements as I see them prior to merging:

• Process currently does not match the existing docs building process from CI -- this process of adding content will need to change the CI process as well (once the process is agreed upon)
• Using sed to insert at the top of the file is dropping the final blank line from the incoming index.md -- we need this blank line to be copied or a new blank be added otherwise "Packages" will be put in the final paragraph on the MkDocs index.md
• Actual content being inserted is meek right now -- improvements are in the future, my initial work here was to "get it working" rather than focus too much on "is it perfect"

[SeanTAllen]

Process currently does not match the existing docs building process from CI -- this process of adding content will need to change the CI process as well (once the process is agreed upon)

What does this mean? what process?

[SeanTAllen]

There's only 1 file in this PR. I think you missed adding something.

[rhagenson]

I did not change the CI process and only added the one file at this time with the proposed method for inserting this PR's index.md in the correct place. I ran out of time tonight to fix the missing blank line between the end of this PR's index.md and the start of the ponyc public docs generator's index.md.

If having the two sed lines is a good solution, I will edit the CI process to match and include it in this PR. That will fix statement of mine that you quoted. (I also now see how confusingly written that statement was on reading it now.)

[SeanTAllen]

So there is currently an "index page" of some sort. what would the change be? i'm unclear.

Can you give an example of existing content and what it would be afterwards or perhaps the changes to the stdlib generation so I can understand where this index would go and how it would be "seded" in. I'm not following at moment from the original description.

[rhagenson]

The change is adding the content from a new packages/stdlib/index.md at the start of stdlib-docs/docs/index.md after running ponyc --docs-public packages/stdlib to create stdlib-docs/docs/index.md.

This is what is in my Building Documentation Locally subsection of the committed file. Whatever is in packages/stdlib/index.md gets dropped above the Packages list that is the only content in stdlib-docs/docs/index.md after running ponyc --docs-public packages/stdlib.

[SeanTAllen]

@rhagenson should this be closed?