Add documentation workflow. #2313
Conversation
63b14cf to
06719e4
Compare
06719e4 to
fb40960
Compare
fb40960 to
5ec8f3a
Compare
5ec8f3a to
21101c8
Compare
21101c8 to
9870bc4
Compare
dff122b to
74f1b78
Compare
74f1b78 to
f00afb5
Compare
f00afb5 to
b6d6c15
Compare
7ef9a3a to
7daa3bc
Compare
7daa3bc to
0a2192e
Compare
This allows us to parse the alt text from Markdown images, formatting a header text correctly (using the alt text). Without this PR, if a Markdown file has an image instead of a title, that image will be used in the table of contents, which is unreadable and undesirable. Used in <rack/rack#2313>. --------- Co-authored-by: Stan Lo <stan001212@gmail.com>
32db6b3 to
45e220f
Compare
226dbb4 to
4e74a89
Compare
There was a problem hiding this comment.
Assuming I understand this correctly, this means rack.github.io will reflect the main branch. I don't think that's a good idea. I think we should change it to reflect the most recent release (3.1.12). The vast majority of our users are using rack via gems, not running the main branch, and the documentation should be targeted at them. We would not want a user running the latest release version to look at the documentation, try something based on it, and find out it doesn't work because the feature isn't in any release.
We could consider subdirectories per version (e.g. 2.2, 3.0, 3.1), but that's probably more difficult to setup.
|
Unfortunately GitHub pages is per repository and there is no per-branch feature. It would make situations like this simpler. I normally run my documentation from While I understand your point, I'm against running the documentation workflow on 3-1-stable branch (or other stable branches) in this PR. No matter what, the issue you suggest will be a problem (half our user base is still on Rack 2.2). In addition, we don't backport documentation fixes/changes, so I think you've under-estimated the amount of work required to make the documentation look good on 3-1-stable. A better solution is for us to clearly document the intended version support in the code, e.g. "This class was introduced in Rack 2.2" or "This method was introduced in Rack 3.1". That is a lot of work, but also has significant benefit for users. Another solution would be to simply say "This documentation is for the main branch of Rack, some features may not be released yet". I'm happy to add that to the readme so that users at least are made aware. Finally, I'm not against a follow up PR to address this more holistically, e.g. having separate sets of documentation per version, e.g. generating documentation from released gems in addition to the main branch. However, I think that's out of scope for this PR. |
|
I'm not in favor of adding documentation to methods explaining when they were introduced. Can we generate the documentation for |
Generate the RDoc and push it to GitHub pages.
https://rack.github.io/rack/