Bring all Rhino docs under version control and host on GitHub Pages

[p-bakker]

Currently we don't use the Github Wiki functionality and some of the links in our README point to archived pages on developer.mozilla.org

It looks like an attempt was made to move that content to Github Pages, but it looks like that effort isn't up to date and keeping it up to date is more effort then when the content would be in the project wiki

So I propose to enable the Wiki, move the content that is currently on developer.mozilla.org and/or our Github Pages there and then remove the documentation content from our Github Pages and update the links in our README's to point to our Wiki.

The only thing that might still be hosted on our Github page could be the Rhino JavaDocs, but those seem out of date (v1.7.11 currently). The compat tables from there can be tossed I think as Rhino is now included in https://kangax.github.io/compat-table/es6/

[gbrail]

It'd be great if we could get everything on the Mozilla Wiki into the GitHub Wiki instead! Yes, I've tried to use gh-pages at various points in the past but the need to manually update things makes it frustrating. I'm glad to hear that we're supported in the compat-table again even though we're an "obsolete platform." I hope your work will make it easier for us to prioritize at least getting farther on ES6 features.

…

On Thu, Jun 24, 2021 at 11:58 PM Paul Bakker ***@***.***> wrote: Currently we don't use the Github Wiki functionality and some of the links in our README point to archived pages on developer.mozilla.org It looks like an attempt was made to move that content to Github Pages, but it looks like that effort isn't up to date and keeping it up to date is more effort then when the content would be in the project wiki So I propose to enable the Wiki, move the content that is currently on developer.mozilla.org and/or our Github Pages there and then remove the documentation content from our Github Pages and update the links in our README's to point to our Wiki. The only thing that might still be hosted on our Github page could be the Rhino JavaDocs, but those seem out of date (v1.7.11 currently). The compat tables from there can be tossed I think as Rhino is now included in https://kangax.github.io/compat-table/es6/ — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#954>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAD7I23LEFCILL2EDA3WVFLTUQSLFANCNFSM47JJOLOA> .

[p-bakker]

Great, think you'll have to enable the wiki and then we're off to the races 🙂

[tonygermano]

I'd actually suggest continuing to use the gh-pages (which I wasn't aware existed before now) and point the links there. Github's wikis kind of suck. They rightfully can only be edited by collaborators by default, and I don't think you'd want to make it public.

You can accept PRs for gh-pages from anyone, but not for the wiki.

[tonygermano]

On the topic of github features, though, Discussions might be something useful to turn on. It's something like a poor StackOverflow clone. It would actually be a more appropriate place to have discussions like this than on an issue until a decision was made. It could also replace be an alternative to the mailing list and be a place for people to ask questions related to the use of Rhino that aren't actually issues.

[gbrail]

It was super easy to turn both of those things on, so I turned them on!

…

On Mon, Jun 28, 2021 at 1:19 PM tonygermano ***@***.***> wrote: On the topic of github features, though, Discussions might be something useful to turn on. It's something like a poor StackOverflow clone. It would actually be a more appropriate place to have discussions like this than on an issue until a decision was made. It could also replace the mailing list and be a place for people to ask questions related to the use of Rhino that aren't actually issues. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#954 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAD7I232EBXBNT64WURRSFTTVDKNNANCNFSM47JJOLOA> .

[p-bakker]

I'd actually suggest continuing to use the gh-pages (which I wasn't aware existed before now) and point the links there. Github's wikis kind of suck. They rightfully can only be edited by collaborators by default, and I don't think you'd want to make it public.

Mmm, wasnt aware of that. Did some research and there are ways to accept PR's on wiki content, but its cumbersome: the wiki is it's own git repo, but doesn't come with the bells and whistles that project repo's come with, like PR's or forking. But you can manually clone them, to work on them offline or to put them in a regular project repo, so you can have PR's on them (but you'd have to sync that copy with the original wiki repo somehow). All in all not straight-forward...

The alternative, gh-pages, I'm not very familiar with, so I'll dig in a bit. Wanna be able to use markdown, instead of having to handcode HTML, nor do I think it would be nice that you'd need to install a bunch of extra tooling locally. A quick tests seems to suggest you can just put markdown files in the hg-pages branch and it'll render them as HTMl.

Will keep you posted

[p-bakker]

k, got something going :-) Found a theme for Github Pages that does most of the heavy lifting, allowing us to focus on writing content in MarkDown

Now in the process of setting up a page structure and seeing which content currently on https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino is still relevant

One thing to decide though: currently our Github Pages are sourced from the gh-pages branch, which means switching branches if you want to work on the docs and because it has a completely different folder structure as the master branch, on both sides we'd have to start git ignoring the other's folders, else things are a bit messy.

As far as I can tell, you can also source the content for Github Pages from a folder in any other branch, so we could instead create a docs folder in the master branch and put all the documentation in there. Extra benefit is that if making code changes in master that also require changes to the docs, both can be in the same PR.

Thoughts?

[p-bakker]

Check out https://p-bakker.github.io/rhino/ to get an idea where this might be going

[gbrail]

I used the gh-pages branch in the past to store the compat table (which I still find useful since it tracks many versions of Rhino) and abortedly to store Javadoc. I too find the gh-pages branch annoying to work with, although the "git worktree" feature works very nicely for that now. It is very nice to just edit Markdown and have it rendered by GitHub. If there's a way to have the gh-pages in a regular directory of master, however, I think that would be preferable for everyone. Thanks for figuring this out!

…

On Thu, Jul 1, 2021 at 4:49 AM Paul Bakker ***@***.***> wrote: Check out https://p-bakker.github.io/rhino/ to get an idea where this might be going — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#954 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAD7I2YBXU3F3EJG6YECFM3TVRI5ZANCNFSM47JJOLOA> .

[p-bakker]

If you go to Settings > Pages, you can select the branch and root folder from which Github Pages sources its content.

Note that you can also enable HTTPS there, which I think we should do

[C-Masuda]

Any ETA on this? Right now it looks like Rhino Documentation doesn't exist anywhere... See here. @p-bakker

[p-bakker]

Mmm, didn't know Mozilla took all archived documentation offline...

That changes the priority a bit, as before I was just working on it on and off.

I'll try to get the basic scaffolding up in a PR asap, but that will probably be a few weeks. After that, there will probably be a lot of pages that still need to be petted over and/or (re)written, but others could then chip in

[p-bakker]

Note: the source of all Rhino documentation that was available on MDN but has now been removed can be found here: https://github.com/mdn/archived-content/tree/main/files/en-us/mozilla/projects/rhino

[p-bakker]

Note: we can submit a PR to https://github.com/mdn/yari to get all the old MDN url's to redirect to our new documentations (once it's available), see mdn/yari#3323 (comment)

[p-bakker]

Do we care about keeping RELEASE-NOTES.md? It's basically a duplicate of all the info already recorded on all the releases in GitHub itself.

[peterharaszin]

I would also suggest updating the link in the official README.md file:
https://github.com/mozilla/rhino/blob/master/README.md

Thanks in advance!

[p-bakker]

Quick update: check out https://p-bakker.github.io/rhino/

Still mostly the old content and want to clean up a bit more before I cretae the PR:

• sort out the overlap between Documentation, Overview and Home
• cleanup the Roadmap page

Any comments welcome

[p-bakker]

Does anyone know about optLevels in Rhino? See #1123 for a question I have about it

[andrewloutfi]

Seeing the link under "More resources if you get stuck" in the README resolving to a 404 page.

Might be worth running a tool like markdown-link-check over the repo.

[reviewher]

The link in the sidebar https://www.mozilla.org/rhino/ points to a nonexistent website.

@p-bakker even if it is not 100%, https://p-bakker.github.io/rhino/ is a far better resource than the 404 page on the Mozilla site.

[p-bakker]

@gbrail I've taken my https://github.com/p-bakker/rhino/tree/docs_on_the_move branch (from which the https://p-bakker.github.io/rhino/ Github Page is sourced) and extracted the contents (and history) of just the docs folder to a new repo: https://github.com/rhino/rhino.github.io

So now we have what was before just hosted on my personal fork also on https://rhino.github.io/

I think we should change website in the About section on this repo to point to https://rhino.github.io/ instead of https://www.mozilla.org/rhino/ and then toss out the entire /docs/ folder in this repo and update the link to the archived page in https://github.com/mozilla/rhino#documentation

Think having all the docs in a separate repo will be better going forward

[p-bakker]

Just to be clear: what is up at https://rhino.github.io/ / https://p-bakker.github.io/rhino/ leaves much to be desired, but it's better than nothing and at least no that its in a (non-personal) repo, others could contribute

[p-bakker]

@gbrail could you change the https://www.mozilla.org/rhino/ link in the about section of this repo to point to https://rhino.github.io/ instead?

[p-bakker]

@gbrail any update on the above? Or don't you think we should do this?

[gbrail]

Let me reply to this so that I can actually get to it soon…

…

On Tue, May 14, 2024 at 10:49 AM Paul Bakker ***@***.***> wrote: @gbrail <https://github.com/gbrail> any update on the above? Or don't you think we should do this? — Reply to this email directly, view it on GitHub <#954 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAD7I26PHUC3SWJN7P4TCMLZCJFCVAVCNFSM47JJOLOKU5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMJRGA3TSNRVGQZA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[gbrail]

I changed the link -- I hope that will at least help some people find where the more recent docs are!

…

On Tue, May 14, 2024 at 11:01 AM Gregory Brail ***@***.***> wrote: Let me reply to this so that I can actually get to it soon… On Tue, May 14, 2024 at 10:49 AM Paul Bakker ***@***.***> wrote: > @gbrail <https://github.com/gbrail> any update on the above? Or don't > you think we should do this? > > — > Reply to this email directly, view it on GitHub > <#954 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AAD7I26PHUC3SWJN7P4TCMLZCJFCVAVCNFSM47JJOLOKU5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMJRGA3TSNRVGQZA> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

[p-bakker]

Closing as rhino.github.io is now live with all the old documentation what was previously hosted on mozilla.org