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

Updating/Publishing the docs/ directory #774

Closed
ryan-williams opened this issue Aug 14, 2015 · 4 comments
Closed

Updating/Publishing the docs/ directory #774

ryan-williams opened this issue Aug 14, 2015 · 4 comments

Comments

@ryan-williams
Copy link
Member

@ryan-williams ryan-williams commented Aug 14, 2015

I only realized that the docs/ directory exists recently, when refactoring README.md (#763, #764).

@fnothaft implied on #764 that the docs there get distributed via released artifacts, but I don't see any in adam-distribution_2.10-0.17.0-bin.tar.gz.

It seems like there was a lot of somewhat-duplicated markdown living there, vs. what was in README; now the README is very different.

Are builds of docs/ available on the internet anywhere? How should we keep them updated / consistent with README.md? Is it up to anyone making changes to update the docs in both places?

Should we move towards setting up e.g. readthedocs.org builds of the docs for each version? Should the README point at those? I generally like that approach, though some way to also publish docs for random non-release SHAs/nightly-snapshots or something would also be good and has been lacking in other projects who've done something like this, e.g. Spark.

@massie
Copy link
Member

@massie massie commented Aug 14, 2015

The docs are published with the releases. I had hoped that by using simple markdown, the barrier to updating them would be low. Unfortunately, we haven't been updating them once created, e.g. git log -- docs.

I'm open to any suggestions about how to do documentation better. I haven't used readthedocs.org so I can't comment from experience. I hope what we choose needs to create standalone docs (e.g. PDF, html, etc) and not be dependent on services.

@ryan-williams
Copy link
Member Author

@ryan-williams ryan-williams commented Aug 14, 2015

Ah, thx @massie, I see the PDF and HTML downloads on the releases/ page now. Thanks for the additional context as well; I don't have any great ideas at the moment but I'll leave this here until inspiration strikes someone.

@fnothaft fnothaft added this to the 1.0.0 milestone Mar 3, 2017
@fnothaft
Copy link
Member

@fnothaft fnothaft commented Mar 3, 2017

We should push this to our github pages.

@heuermh
Copy link
Member

@heuermh heuermh commented Apr 11, 2017

Fixed by #1461.

@heuermh heuermh closed this Apr 11, 2017
@heuermh heuermh modified the milestones: 1.0.0, 0.23.0 Dec 7, 2017
@heuermh heuermh added this to Completed in Release 0.23.0 Jan 4, 2018
@heuermh heuermh moved this from Triage to Completed in Release 1.0.0 Jan 4, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Release 1.0.0
Completed
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.