Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

No indication on standard lib site how to contribute #1829

Open
SeanTAllen opened this issue Apr 8, 2017 · 8 comments · May be fixed by #3905
Open

No indication on standard lib site how to contribute #1829

SeanTAllen opened this issue Apr 8, 2017 · 8 comments · May be fixed by #3905
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers help wanted Extra attention is needed

Comments

@SeanTAllen
Copy link
Member

Its not reasonable for us to assume that when people find gaps in the standard library documentation that they know they can contribute by opening a PR here. That should be included in standard library doc site.

@Pyrrh
Copy link

Pyrrh commented Dec 29, 2017

Hi! I'd love to help with this. However, I'm not sure where I would need to add this information in order to make it appear above the list of Packages on the main page of the stdlib documentation. Can you point me in the right direction?

@Pyrrh
Copy link

Pyrrh commented Dec 29, 2017

(Alternately perhaps it needs to go in the tutorial somewhere?)

@SeanTAllen
Copy link
Member Author

@Pyrrh awesome.

So... there's documentation generation for the standard library built into the pony compiler.
That documentation is then uploaded to a repo for hosting. That is done using the docs-online Makefile target.

It first does regular documentation generation using the docs target. Then it does other modifications currently:

docs-online: docs
$(SILENT)$(SED_INPLACE) 's/site_name:\ stdlib/site_name:\ Pony Standard Library/' stdlib-docs/mkdocs.yml

If you generate docs, you'll see the mkdocs format content that gets created. This can be added to, etc to change the index to include information on how to contribute to the standard library; which really means, pointing folks at the RFC documentation.

Having a general "header" after the <hr> and before the package list would be a good place for such information (as well as any others we might want to have).

You could add content in .docs to be added in to the index.

Hopefully this makes sense. If not now, then once you get started.

@SeanTAllen SeanTAllen added good first issue Good for newcomers documentation Improvements or additions to documentation and removed complexity: beginner friendly labels May 12, 2020
@rhagenson
Copy link
Member

@SeanTAllen I started work on this, but there is no longer a docs target in the Makefile. Is this intentional, or was it incidental?

I was able to get the docs locally by following the steps in CI so I can make progress tonight, but wanted to note the lack of docs target.

@SeanTAllen
Copy link
Member Author

@rhagenson intentional.

@rhagenson
Copy link
Member

I see. Where would be the correct place to then add this "How to contribute" content so it appears on the index page?

@SeanTAllen
Copy link
Member Author

It would have to be part of the script that creates the docs to update the generated mkdocs to include some additional content.

@rhagenson
Copy link
Member

Okay. Similar to how it was done back when the docs target did exist. Thank you.

@rhagenson rhagenson linked a pull request Oct 22, 2021 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers help wanted Extra attention is needed
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants