Contributing to documentation 101

[Pryme8]

*** See last post this one was an accident.

[Wingnut]

ohhh... that thing.  *nod*  I use a similar device called 'GitKraken'... likely the same thing.

GitKraken, Tortoise, and GitHub Desktop, have all refused to allow push to my free repo.  I have never had a successful push from home... no matter the gui method or shell attempts.  Fetches and clones TO my home, not a problem.

SO you say it is something I am doing wrong, because I should be able to push from home with free account?  nod.  (thx)  Back to work for me. 

PS:  Your icon is... umm... yeah... much happier-looking now... I suppose.    Thx for the accommodating.

[Pryme8]

yea there is something wrong if you cant push (im like 89% sure).  Id recommend downloading desktop and making sure all your firewall settings are correct.

and this is gonna sound dumb cause I think its supposed to inherently, but are you executing the shell with administrator rights?  You might need to elevate its rights in the exe's properties on every execution. <-- I don't even know if im telling you the truth here.

[Wingnut]

Thx.  Good thoughts.  Firewall is probably fine because I get good SSH auth-in to github.  But still, I'm going to check all your ideas.  I'm in full info-hunting mode on this one.

Possibly... I don't have a good understanding of my remote and origin urls for push.  I know I can't push to bjsdocs master - not allowed.  It looks like my push url targets Wingnutt docs repo... all fine.

Maybe... I can't push to my master... because it is a fork of bjsdocs master... and thus carries the same permissions (almost like locked-sync).  Maybe I need to branch from my master first, then only push into the branch.  Or push a whole new branch. 

I have much to learn.  But I would hate to put many more hours into it... if all I needed was $7/month. 

[JohnK]

@Wingnut glad that your editing is going well, mine just went flat. As you have re-woken this topic and my question directly relates to it I will ask my question here rather than starting a new topic. Its not really a BJS issue but you do get a better class of help here than say St**ck****fl*w.

I was adding some pages to documentation on generating trees. When I tried to check that it locally using grunt serve I got Firefox can't establish a connection to the server at localhost:3000. Neither Chrome nor Edge connects either.

This is a screenshot of messages when working locally.

 

I am using windows 10, firefox 45.0.2

Any ideas where I go from here?

[GameMonetize]

Hey, just run "grunt build" first

[JohnK]

Thank you @Deltakosh that worked.

[Wingnut]

So, John... what did you think of "the build"?  Ain't that the most amazing thing ya ever seen?  See why I describe it as robots vs. data?  Gruesome battleground!

The robot factories produce an amazing pile of talking data-processing bots, and off they go, grunting and gulping, and reporting, and reporting, and reporting.    too fun.  If we could "watch" a build... in a BJS scene, using primitives to represent the robots (tasks)... that would be a massive polygon-a-thon, eh?  A completely different kind of reports coming from the robots (no longer text).  Yum!  Goofy.

[JohnK]

"The build" was amazing but somewhere my battlefield warriors seem to have been taken hostage. My last contribution to documentation is being held prisoner. You can see them in prison in github land but they are being kept out of action. However Field Marshall Deltakosh has set Generals Temechon and RannanW onto it so soon all will be back into service. I am still waiting to see if I have to face a court martial sending my grunts out with inappropriate deployment of git commands.

[GameMonetize]

You're in!! http://doc.babylonjs.com/extensions/SPS_Tree_Generator

[Wingnut]

You are "Cubees" at github, John?  COOOOOL! 

I saw the tree generator work happening in github, and I really wanted to announce it early... because I am definitely a forest junkie... I LOVE TREES!  (Normal for a treehugger like me).  But then I thought... nah, the guy might want to throw a release party, and I would ruin the surprise.  Trees!  YAY!

Damned good comedy going-on, too.  Love it.  Ok, back to contributing talk.  Are you using your new laptop for the builds, Johnnycakes?  What's the build time for you, if you don't mind me asking?  Just under 57 secs, here.  Express server (grunt serve) launched ok?

I think... if you use the HTML inspector in your browser (it lets you do live edits)... to edit something (like a style) on your local docs website in real time, Express server will get an error, and possibly flop.  Not sure why, yet.  Could be me, doing something wrong.  Or maybe, that is expected.  *shrug*  Just thought I'd mention it. 

Are you using Github Desktop, Tortoise, GitKraken, or similar?  Having any trouble freshening your home repo?  In GitKraken, I believe it's the fast-forward button.  In Git Desktop, I think it's the sync button.  GitKraken 1.3 is broken at the moment, won't finish loading the repo.  So, stay with 1.2 or earlier... if you use GK.

Congrats on your home docs build, J.  Handy for testing, especially for table of contents on docs.

[JohnK]

Hi Wingy hope the trees extension will generate more and new improved trees with additional documentation. NasimiAsl has said he will add the tree found here http://melyon.ir/preview/index/40426 when he's not so busy (give how busy he has been with shaders and geometry that good be a while yet) .

My use of git and github is now infrequent and I have to do a lot of re-reading when I come to use it again. I was using github desktop but it uses a portable version of git and the serial number kept changing for some reason and I kept having to change the PATH in environmental variables. Also I had to still use the cmd to do what I needed so have now ditched this in favour of a full version of git and use tortoisegit. At the moment I think I have got the hang of fetching the up to date version of BabylonJs Documentation, merging with my local master, create a new branch make changes and push everything to my repository and creating a pull request.

Didn't do any timings on grunt build - just happy to see it battling away and for grunt serve to then work.

[NasimiAsl]

Try to find a way to make faster GeometryBuilder

Tree generator is in side the geometryBuilder ( and Material with Shader Builder) so After finish GeometryBuilder I can Add 3 new Generator(Wall , Surface, Tree) 

[webGLmmk]

dont know very much about git, or Node.js.  I'm also using Linux Mint, not windows, and I'm not using a git tool. I forked the Documentation repo to my own github account, then cloned that locally. I already have Node installed, so I just ran sudo npm update. that looked successful, so then I ran "grunt serve".

It opened a browser window with the "Unable To Connect" message, did not access Localhost:3000

in Terminal, I got this:

 

 

There's LOADS I don't understand yet about using Grunt etc etc, but I was hoping someone could point me in a general direction, before I start reading npm/grunt docs like a needle in a haystack, or following shady directions upvoted on Stack Overflow.

I know I can edit a file in the repo itself, but now that this has failed, I want it to work.

 

 

[JohnK]

@gson78 have a look back at my post this topic 5 May and Deltkosh's reply grunt build before grunt serve worked for me.

[webGLmmk]

7 hours ago, JohnK said:

@gson78 have a look back at my post this topic 5 May and Deltkosh's reply grunt build before grunt serve worked for me.

 

 

Thanks, not the same issue I think. So, I'll do it in github and once I'm more familiar with all this, figure it out...unless someone else comes along and knows what I'm looking at...

[JohnK]

Viewing documentation in github the 'Public' folder has no html files. Knowing that using grunt build locally will produce these html files I tried following thinking that I would PR the master with just the changes and no created html files.

Clone Documentation repo., make changes in local master, create local branch from master, checkout branch, grunt build, grunt serve to check if changes work, checkout master to do the PR. However I see that the master also now has all the html files created by grunt build.

1. Am I doing something wrong.
2. Does it matter if I PR and the html files are in there?

[Temechon]

You're not doing something wrong, but you must not commit these HTML file, only MD files

Thanks !

[JohnK]

Would this be a better sequence

Clone documentation repo into local documentation folder

Make changes to local master.

Copy local documentation folder.

Use grunt build in copy and test result with grunt serve.

When changes OK PR original local master.

[Wingnut]

Heya @JohnK!  Only 3 months to get a response! 

I just grunt-build on my local master... no need to copy.  Express server should fire-up automatically at the end of the build, a browser will launch, and the LOCAL port 3000 docs site is browsed.  Plus, there's a change-checker active, then.  If you modify the .md... while the express server is still running... you will see the build auto-start again.  Something is watching for changes.  It's pretty cool.  Edit an .md, and it is automatically re-included in the build.  It works great.

But I do an odd "submit" method.  Once I get the .md looking good, and know that it's html/toc look good on the localhost docs website... then I move the .md file directly to my online github docs repo... via a paste... and then submit the PR from there.  I have never gotten a local branch to be pushed to my online repo.  I get an error like "GitHub does not provide a command line interface"... which... as best I can tell... means... give us $7 per month if you want this feature.

Not sure if I'm correct on that, though.  Auth-in to github looks like it is working fine... and trying to find out what "does not provide a command line interface" actually means... is a web-search nightmare that has produced no good results.  Lots of webpages mention that line.  Nobody says what it means... not even github help pages.

Anyway, I just wanted to mention to ALL... that an interesting forum topic about docs... is happening here,  and don't forget about our cool Tutorial Talk thread, too.  These are sub-conversations of this fine topic, ya know?    Be well... gang.

[Temechon]

Dear doc contributors, 

The documentation has been updated from 'jade' to 'pug' by @Wink (thanks man!), as jade is now deprecated. In order to it, you just have to do : 
npm install
npm prune
and that's all !
Happy coding !

 

[GameMonetize]

We should update readme then

[Wink]

I've created PR https://github.com/BabylonJS/Documentation/pull/289 to add some updating instructions.

[JCPalmer]

I hesitate to add to a very long topic (implying I read the whole thing), but am in the process of adding a new tutorial.  There is a table, bullet list, and a few code sections to break up the text.  Was thinking about adding a gratuitous picture.  I see all examples using full path urls to external servers.

On some of the markups I have done on Github, I have experimented having the pictures right in the repo, in a sub-directory, doc-assist.  I then referred to them like <img src="doc-assist/MH_community.jpg">, example. 

Not having the image in the repo or in the final site is pretty fragile.  I suppose additional "grunting" is involved or this wouldn't currently be this way.  If images cannot be in the documentation repo, I just leave pictures out.  Let 'em eat cake.

[Temechon]

You can add the image in the repo, no problem. Just place it in https://github.com/BabylonJS/Documentation/tree/master/public/img and reference it like this : 

src="img/..."