Idea : migration mobx docs to Docusaurus ?

[kasiriveni]

Welcome to MobX. Please provide as much relevant information as possible!

I have a:

1. Question: Feel free to just state your question. For a quick answer, there are usually people online at our Gitter channel
2. Documentation improvement. Please don't open an issue but create a PR instead!
3. Issue:

• Provide error messages including stacktrace
• Provide a minimal sample reproduction. Create a reproduction based on this sandbox
• Did you check this issue wasn't filed before?
• Elaborate on your issue. What behavior did you expect?
• State the versions of MobX and relevant libraries. Which browser / node / ... version?

3. Idea:

• What problem would it solve for you?
• Do you think others will benefit from this change as well and it should in core package (see also mobx-utils)?
• Are you willing to (attempt) a PR yourself?

Please tick the appropriate boxes. Feel free to remove the other sections.

Please be sure to close your issues promptly.

[kasiriveni]

Feedback

[fi3ework]

What is the advantage of Docusaurus compared to GitBook 😀

[mweststrate]

Gitbook is not the best indeed. I'm having lately some fun with docz as well, seems to cover all needs nicely as well Op do 3 jan. 2019 om 08:07 schreef Wee <[email protected]>:

…

What is the advantage of Docusaurus compared to GitBook 😀 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#1859 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABvGhKfbNcKxOVuc01m65FXGCOJAzeCOks5u_aw7gaJpZM4ZnmgY> .

[mweststrate]

also: since awesome-mobx doesnt seem really actively maintained, we could link to the best resources in there as well.

[cloverich]

What would be a good next step on this issue? I see #1470 is updating the docs but cannot tell if that would be part of this issue or not. Migrating existing docs to docusaurus / docz? Or using one of them based on what's done in #1470 ?

[mweststrate]

#1470 can be ignored for now 😊 Op ma 6 mei 2019 16:24 schreef chris <[email protected]>:

…

What would be a good next step on this issue? I see #1470 <#1470> is updating the docs but cannot tell if that would be part of this issue or not. Migrating existing docs to docusaurus / docz? Or using one of them based on what's done in #1470 <#1470> ? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1859 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAN4NBFWY3T4WLNF6MKH2XTPUA5S7ANCNFSM4GM6NAMA> .

[danielkcz]

Even though Gitbook is not the best, it serves the cause. So unless some enthusiast has a lot of free time and wants to try some other platform out of curiosity, we won't be migrating it.

Will close after a week or so without activity.

[goldylucks]

Maybe a list of gitbook's shortcomings for mobx would help clarify the value/investment ratio here?

"Gitbook is not the best" doesn't give much info (at least to someone new like me)

[danielkcz]

@goldylucks I would probably focus on a different angle. What would we gain by migrating to a different platform? I don't honestly know that much about GitBook (or Docusaurus in fact), I mostly just said what Michel did in slightly different words.

[goldylucks]

@FredyC I thought this is up for discussion since the issue is still open. Never mind then :)

[danielkcz]

Well, the discussion is certainly open, I am not saying we should not be doing it. The more important question is "why should we do it".

Although now I see there are two linked issues above that has some mild issues. It's true that Docusaurus or anything is probably more polished these days. And possibly more mobile friendly. Perhaps if someone wants to learn how to work with Docusaurus platform, it might be a good opportunity. I've recently made https://mobx-react.js.org with Docz and it was ok, but I wouldn't probably recommend it for these docs here.

[mweststrate]

The why is mostly that gitbook is no longer maintained (in the shape we use it, as local tool), and I think at this moment I am the only one who can publish the docs. It works only on node 6.10 (and not later), and apparantly there is some specific stuff in my global npm packages that makes it work for me, but not for anybody else. In other words, it is not a stack we can trust in the future :P

…

On Mon, Jul 1, 2019 at 10:53 PM Daniel K. ***@***.***> wrote: Well, the discussion is certainly open, I am not saying we should not be doing it. The more important question is "why should we do it". Although now I see there are two linked issues above that has some mild issues. It's true that Docusaurus or anything is probably more polished these days. And possibly more mobile friendly. Perhaps if someone wants to learn how to work with Docusaurus platform, it might be a good opportunity. I've recently made https://mobx-react.js.org with Docz and it was ok, but I wouldn't probably recommend it for these docs here. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1859?email_source=notifications&email_token=AAN4NBA4FZNIBCPXA2PKSJTP5JVFNA5CNFSM4GM6NAMKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODY7KI6Q#issuecomment-507421818>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAN4NBEGM2MWFZ7LGTOAAJLP5JVFNANCNFSM4GM6NAMA> .

[danielkcz]

I've noticed there is GitBook V2 which is actively maintained, but I am failing to find some migration guide. It could be another option if they haven't changed it too much.

But of course, Docusaurus feels much more sleek and fancy. We just need a volunteer who wants to try out that platform and moving the actual content shouldn't be that hard considering it's all just Markdown.

[cloverich]

I spent a little time researching docusaurus and docz, as well as looking into how the current publishing works. A few thoughts:

1. Per @mweststrate comment the current publishing is a bit confusing and seems to rely on some global modules

2. I briefly looked into docusaurus, docz, gitbook. Whatever the various merits, docusaurus is targeted at this specific use case (docs + blog), is well maintained, and is in wide use. Whether or not it is the best choice it is certainly a healthy choice

I would be happy to help or even do all the leg work here if you all can entertain a few questions I have as I go. I'll need to review my notes but off the top of my head:

• Would it be ok to move the (markdown) documentation to the main branch? Not strictly required, but I think it would make the workflow more obvious
• If so, would it be ok to add the docusaurus toolchain, scripts, and documentation (about publishing the docs) to master as well?

Docusaurus has some built-in scripts for github pages, where running its publish script will generate the site and commit / push it to the gh-pages branch. I imagine the workflow is something like:

• Generate documentation from master
• Commit the generated documentation to the gh-pages branch, push

So working from master could be a good choice, but even if not, I'd highly recommend having the publishing (dev) dependencies added somewhere along with the scripts. As a next step I could try forking the repo and implementing this work, then publishing from there to see what it looks like. Open to suggestions.

Hope this is helpful.

[danielkcz]

• Would it be ok to move the (markdown) documentation to the main branch? Not strictly required, but I think it would make the workflow more obvious

I think it makes sense in case we would move hosting somewhere else (preferably Netlify) instead of gh-pages (which need a separate branch).

• If so, would it be ok to add the docusaurus toolchain, scripts, and documentation (about publishing the docs) to master as well?

It certainly should have it's own package.json contained within docs folder. We can utilize Yarn Workspace for ease of use.

Having docs tied with a code gives also an advantage of a relation an actual version of MobX and can be updated with a single PR. The separate branch needs to be tagged, but nobody does that.

[mweststrate]

I think docs in master would be great, a separate branch for docs is annoying in many ways. So feel free to proceed!

[cloverich]

Hey all -- I made significant progress on this before starting a new job (and have a 5 mo old, so busy!) -- but I'm ready to start moving on this again. Wanted to leave a note on the current status and get some feedback.

1. I have a PR open into my fork of master, since there is still so much to do. But I can turn that into a PR here whenever. https://github.com/cloverich/mobx/pull/1 - I have bullet lists / notes there.

2. I published the work in progress here, docs section here. There are numerous css / layout issues I"m fixing (ex: the parser doesn't like the collapsible egghead sections). What I need help with specifically is what to put on the landing page(s)

3. Re gh-pages, I use Netlify for personal sites and like it. But docusaurus has first class gh-pages support. The process is basically: Keep docs on master (as I"ve done), run an npm script (from master), and its handles merging to the branch and pushing it to github. I think it would be simplest to finish this work using github pages but doing so would mean you'd have to nuke the current site when we merge. So maybe not preferable.

So that's where its at now. I'll start updating that branch again soon and please let me know if y'all have any other thoughts :)

[danielkcz]

Thanks for the great work @cloverich. Cannot help much with a landing site content, that are some marketing-like level things :)

My view on gh-pages:

• It's super confusing to contribute. Just recently there was Improvement of contribution flow. #2098 which shows it's not really obvious how it works. It would need to be explained specifically on the site.
• When someone is submitting PR that's worth mentioning in docs, they have to make separate PR to a gh-pages branch which makes it rather difficult.
• That implies the code changes are NOT versioned with docs changes.
• Correct me if I am wrong, but even with premium Docusaurus support for gh-pages, someone has to go and publish it, right? That's a major problem here with scarce maintainers willing to push that button after each small typo fix. This has to be automatic.
• As a bonus point, we wouldn't need to nuke anything, have the new site in master and when it's ready, just flip the domain.

There is one major disadvantage with Netlify. They don't offer OSS team plans. Only one team is free with a single team member. It may become a problem in the future when some configuration needs to be tweaked and nobody has access to it. I am not sure if there is a better alternative for OSS project though.

Looking at js.org config file with all listed domains it's true that the majority does use gh-pages, but looking at the file like a year ago there is some trend of moving to Netlify instead.

[cloverich]

When someone is submitting PR that's worth mentioning in docs, they have to make separate PR to a gh-pages branch which makes it rather difficult.

Since I moved the docs to master, this won't be necessary any longer. You make the PR to master, and run an npm script also from master

It's super confusing to contribute. Just recently there was #2098 which shows it's not really obvious how it works. It would need to be explained specifically on the site.

The current workflow certainly is -- I still don't think I completely understand it.

Correct me if I am wrong, but even with premium Docusaurus support for gh-pages, someone has to go and publish it, right? That's a major problem here with scarce maintainers willing to push that button after each small typo fix. This has to be automatic.

This is true. You would have to rely on the (existing?) CI system to automate this.

As a bonus point, we wouldn't need to nuke anything

Also true. This is the main sticking point for me still, because my preference would be to finish the transition with gh-pages and then move to netlify as a follow-on step (since the gh-pages flow is already functional).

[danielkcz]

Since I moved the docs to master, this won't be necessary any longer. You make the PR to master, and run an npm script also from master

Wait, I don't follow. How can it be in master and use gh-pages? I thought it has to sit in gh-pages branch specifically? Honestly, I don't know anything about gh-pages. Can it be deployed from master? That would certainly make it more appealing.

Nevermind, I think I understand now, the gh-pages branch or not a requirement. In that case, I think we can stick to it as most of my points are around that. Automating publish with CI shouldn't be that hard (we use CircleCI).

[cloverich]

Exactly. Right now I"m publishing from my branch with the following command:

GIT_USER=cloverich CURRENT_BRANCH=cloverich/docusaurus USE_SSH=true yarn run publish-gh-pages

The script then (I believe):

• Builds the site
• Adds the built site to the gh-pages branch
• commits
• pushes gh-pages

I've removed the docusaurus boilerplate and most of the extraneous content now, so you should be able to look at the branch and get an idea of what files I've moved to master, and what files the docusaurus workflow has (see the website folder).

EDIT: By "look at the branch" i mean look at cloverich/docusaurus -- there's more discussion to be had but some of it can wait for the PR.

[danielkcz]

Hm, so the built content has to be pushed to gh-pages? I guess it makes sense, but I hope it won't be another point of confusion. I mean up until now people got used to sending PR to that branch. If we flip it and that branch will be generated only... 🤔

That's surely the advantage of Netlify, they keep built files there, so it doesn't need to pollute the repo. Such tradeoffs...

Edit to your edit: Yea it definitely looks more approachable now with docs folder sitting in master.

[mweststrate]

I mean up until now people got used to sending PR to that branch.

I don't think that will be an issue

1. The edit button on the docs would no longer point to gh-pages
2. the source files will no longer be in gh-pages

[mweststrate]

@cloverich I've just send a repo invite. Would you mind creating a branch (and PR) on this repo, and pull your changes into that branch? That enables all of us to contribute to the branch, if you like :)

[cloverich]

Thank you :) PR is up. It would be great if someone(s) could quickly review the todos (esp. if anything should be added, crossed off the list, or clarified). Instructions are there for building locally, since we obviously would not want to publish it to gh-pages until its done, if ever.

I will have time to incrementally work on this over the next couple of weeks.

[mweststrate]

This has been done and released a while back. Closing. Thanks again for the work!

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs or questions.