Documentation

Question

Documentation

shirakaba opened this issue 5 years ago · 29 comments

Svelte NodeGUI literally uses React NodeGUI under-the-hood so I'm somewhat tempted to just point users at that docs site and call it a job done; but at the same time, people like things in one place. Wondering whether there's a low-effort way to move forwards on this?

CC @a7ul

Answer 1 · 2021-02-22T07:53:25.000Z

I am thinking there should be at least the guide docs like here for Svelte nodegui. https://react.nodegui.org/docs/guides/getting-started/
You could just copy paste them and make changes to suite svelte instead ?

Answer 2 · 2021-02-22T07:53:58.000Z

Rest of it you can link to react nodegui / nodegui.

The reason is that people do ask for docs and its easier to get started that way.

Answer 3 · 2021-02-22T23:09:33.000Z

Work underway on the docs branch! Hopefully should be able to finish it off over the next week.

Answer 4 · 2021-02-27T14:00:00.000Z

Docs now completely ported, having merged this PR: #27 🎉

@a7ul What would I need to do to publish these docs such that they'd appear with the URL https://svelte.nodegui.org? Is it as simple as npm run deploy? How exactly are you hosting yours, and do I need any new permissions if I'm to do the same?

Note: I've renamed the contents of website/static/CNAME from react.nodegui.org to svelte.nodegui.org.

Answer 5 · 2021-02-27T14:02:43.000Z

It would just be a npm run deploy from your website folder. However, before that, I think atul may have to create a new sub-domain for svelte

Answer 6 · 2021-02-27T14:03:58.000Z

Yep just added it to the DNS settings

Answer 7 · 2021-02-27T14:39:20.000Z

Thanks, @shubhamzanwar and @a7ul!

For my own notes:

https://v2.docusaurus.io/docs/deployment/

# "shirakaba" is the user who has access to the org and project that we configured
# in docusaurus.config.js: `organizationName: "nodegui", projectName: "svelte-nodegui"`
# We use the "main" branch rather than master
GIT_USER=shirakaba CURRENT_BRANCH=main npm run deploy

... However, I'm getting this when it prompts me for GitHub password (which is the correct username and password, as I've just successfully logged into GitHub with them):

Cloning into 'svelte-nodegui-gh-pages'...
remote: Invalid username or password.
fatal: Authentication failed for 'https://github.com/nodegui/svelte-nodegui.git/'
Error: Error: git clone failed
    at runDeploy (/Users/jamie/Documents/git/svelte-nodegui/website/node_modules/@docusaurus/core/lib/commands/deploy.js:79:19)
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! svelte-nodegui@0.0.0 deploy: `docusaurus deploy`
npm ERR! Exit status 1

Maybe it's failing due to 2FA..? When I log into the website via a web browser, there is an additional 2FA step. But when running this in the terminal in VS Code, it didn't present me with one.

The only other explanation I can think of is that it doesn't like working with private repositories. But I think that's probably not the case. I'll look into Docusaurus issues regarding GitHub authentication.

Answer 8 · 2021-02-27T15:03:44.000Z

Maybe it's failing due to 2FA..? When I log into the website via a web browser, there is an additional 2FA step. But when running this in the terminal in VS Code, it didn't present me with one.

I think that must've been the problem. I followed these steps to generate a Personal Access Token, and chose the scopes repo and admin:org. Maybe one or the other scope alone would have sufficed; but either way, this worked. I still used the command:

# In the end, it still prompted me for the password (token) interactively,
# so I think that it's best to not bother passing in the GIT_PASS arg at all.
GIT_USER=shirakaba CURRENT_BRANCH=main GIT_PASS=<password> npm run deploy

Some excerpts of the resulting terminal output (my password is not "main", of course – that was the moment that the terminal prompted for secure input, so it skips that line):

Cloning into 'svelte-nodegui-gh-pages'...
Password for 'https://shirakaba@github.com': 
main
error: pathspec 'origin/gh-pages' did not match any file(s) known to git
Switched to a new branch 'gh-pages'

...

remote: 
remote: Create a pull request for 'gh-pages' on GitHub by visiting:        
remote:      https://github.com/nodegui/svelte-nodegui/pull/new/gh-pages        
remote: 
To https://github.com/nodegui/svelte-nodegui.git
 * [new branch]      gh-pages -> gh-pages
Website is live at https://nodegui.github.io/svelte-nodegui/

Visiting https://nodegui.github.io/svelte-nodegui/ now, I just get a 404, but maybe it needs a few more minutes to appear. I've frequently experienced GitHub Pages being slow at updating, so I'm not worried just yet.

Answer 9 · 2021-02-27T15:05:38.000Z

As a sanity check, the source for the website is visible on the branch gh-pages for this repo: https://github.com/nodegui/svelte-nodegui/blob/gh-pages/index.html

So I guess GitHub Pages is just being really slow..?

Answer 10 · 2021-02-27T15:26:34.000Z

Ah, it looks like GitHub Pages isn't merely being slow – it's not enabled, because the repo is private.

In the GitHub settings for this repo:

Relevant GitHub official docs here.

@a7ul Is GitHub Pages enabled for this repo? What are our options with regards to the site visibility and the repo visibility?

Answer 11 · 2021-02-27T15:28:13.000Z

Hey @shirakaba arent you able to see the settings?
i think you have admin rights 🤔

Answer 12 · 2021-02-27T15:31:09.000Z

I think you'll be able to enable pages once you make the repo public, @shirakaba

You can change visibility when you're ready

Answer 13 · 2021-02-27T15:39:03.000Z

@a7ul That screenshot saying to contact the owner of the repository is what I see in the settings for this repo.

@shubhamzanwar we may be overthinking this, yeah – I’ll be making the repo public within the next 7 days, probably. Need to add typings for event handlers (ideally) and make the starter app first, but after that, we’re ready for a public alpha (beta?) fairly soon. I need to look into @mrsauravsahu’s issue about the phin package, which I’ll do as part of making the starter template.

Answer 14 · 2021-02-27T15:41:56.000Z

yeah i think gh pages on private repo is only available in paid plans

Maybe you can make it public but not post anywhere.

Answer 15 · 2021-02-27T18:43:51.000Z

@a7ul Is this alert (seen in macOS Safari) expected when visiting https://svelte.nodegui.org (disregarding the fact that it'll be pointing to a GitHub 404 page until we make the repo public)?

Certificate details:

Answer 16 · 2021-02-27T19:10:39.000Z

Yes this is expected. Github will create a valid ssl certificate once we enable gh pages.

Answer 17 · 2021-02-27T19:11:34.000Z

Could you make the repo public and we could give it a try ?

Answer 18 · 2021-02-27T19:34:01.000Z

@a7ul Okay, I'll make it public in a second to get this ball rolling. Would help sign up for Algolia, for example.

Though let's not announce any news about it just yet – we need to check that the docs look okay and that the starter template works, and then coordinate the best time to announce for maximum visibility.

Sometime within the next 7 days would be my plan, though!

Answer 19 · 2021-02-27T19:35:37.000Z

Sure 👍🏽

Answer 20 · 2021-02-27T19:37:07.000Z

Works !!!!
https://svelte.nodegui.org/

Answer 21 · 2021-02-27T19:42:12.000Z

@a7ul I'm still getting that "This connection is not private" message, even on a browser that won't have cached it yet – I'll wait for a bit and see if it self-resolves.

Answer 22 · 2021-02-27T19:42:36.000Z

@a7ul It's working on my end now, too!

Answer 23 · 2021-02-27T19:43:06.000Z

Congrats @shirakaba and @mrsauravsahu

Answer 24 · 2021-02-27T19:44:35.000Z

Might have missed this 🙈 on the home page. The image has react code

Answer 25 · 2021-02-27T19:50:30.000Z

@a7ul Ah, good catch! I may well have missed mentions of React if they were invisible to text search 😅

I'll be taking a break for now. If anyone finds further glaring issues with the docs, let's just collect them in this thread and I can address them in one go.

Answer 26 · 2021-02-27T20:15:21.000Z

Woop woop 🚀
Super cool work!

Answer 27 · 2021-02-28T13:18:11.000Z

Might have missed this 🙈 on the home page. The image has react code

Fixed in #33!

@shubhamzanwar we may be overthinking this, yeah – I’ll be making the repo public within the next 7 days, probably. Need to add typings for event handlers (ideally) and make the starter app first, but after that, we’re ready for a public alpha (beta?) fairly soon. I need to look into @mrsauravsahu’s issue about the phin package, which I’ll do as part of making the starter template.

An update on these blockers:

I've made a makeshift fix for the phin issue (#26, solved by commit a62490e). We can revisit it later to find a cleaner fix than exposing it as a peerDependency.
I've been looking into typings for event handlers on branch https://github.com/nodegui/svelte-nodegui/tree/feat/event-handler-typings. I've not had any luck, unfortunately. I'd rather not burn the weekend on it, so won't hold up the release on it (it's a nice-to-have but doesn't block the minimum viable product).
The starter template is ready for use at https://github.com/nodegui/svelte-nodegui-starter.

It would be extremely nice to have @mrsauravsahu's preprocessor integrated, but it's also not technically a release-blocker, as users can manually write in <svelte:options namespace="foreign"/> in the meantime.

Answer 28 · 2021-02-28T13:27:47.000Z

So we could technically make a release announcement any time from now. I'm just thinking of the best time to maximise impact.

I happen to be doing an episode of Svelte Radio to talk about it on Tuesday – but that episode won't be released for 3-4 weeks (and I'm too impatient to wait that long). If we made the official announcement before then, the main benefit is that the hosts would have a chance to read up on it if they wanted to.

That said, my original tweet about the proof-of-concept, posted at 2:49 pm (unclear whether GMT or BST) on Sunday Oct 25th did very well. Which is either 30m or 1h30m from now!

My only other thought is that Tauri (a very similar project) recently made the front page of Hacker News by announcing on a Friday at 8 pm GMT. But I have historically had very poor success on Hacker News. But I've never had any luck on Hacker News anyway, so...

Answer 29 · 2021-03-03T22:26:01.000Z

I'll close this issue in favour of more specific ones, now that we have a docs site up.

I'll announce the project on Twitter, Hacker News, and Reddit sometime between 8-9 pm GMT on Friday! Will share the link to the GitHub repo rather than the docs website.