Jump to content

Contributing to documentation 101


Recommended Posts

haha!  You want ME to add the animation-blending section to the Animations tutorial?  haha.  Are you out of your mind?  :D  Would you like the moon and the stars, as well?

Nooooo, I don't think that is a good idea.  Puppies can't pull Iditarod dogsleds.  (In other words, too technical for me.  I'll get stressed.) 

You add it (please?!), and maybe I will add more to it, later.  thx.   And thanks for merge and build-info, and hooray for auto-build, Raanan.  Cool!

Link to comment
Share on other sites

Features are like joke, if you have to explain them, there are bad :)

If you look at the blending system, I hope you'll find it not to complex because it is basically the same as before with just an option to turn blending on (which literally means: do not start from scratch but from current object's state)

Link to comment
Share on other sites

Thanks T!

Ok, I got the docs website running on my puter RIGHT NOW.  I've done it once before, but it was on a different computer. But yay, we are smokin' now!

And again, 'build' is truly something to behold.  Screens and screens of reports and text and robots talking... just amazing.  I ran into a few issues.  I needed to npm time-grunt and load-grunt-tasks... and that finally allowed npm install.  I also tried to grunt serve before I did a build, and that had some problems... ENOENT (file not found)... but I can't remember what file it was.  Express server LOOKED like it was running fine, but I couldn't browse localhost:3000.

Then I did the build... and started giggling at all the robots... they're more talkative than I, by far.  :)  That went fine (and fun), and then... another attempt at grunt serve... and boom, it just catapulted my browser to my local docs website!  Cooooooool.  Ok, we are on-track... cept... time for Wingy to go play bass guitar for a bunch of sloppy drunks, for 4 hours.  Yee hah, ride 'em cowboy. 

For those who want to try this local babylon docs stuff... see the first post in this thread, and scroll down at our docs github site.  Both docs are easy and well-written.

Sorry for being such a hag, lately.  I'm going to try to fix that.  :)  Party on!

Link to comment
Share on other sites

Hi guys.

I tried another 'build' of the docs, today.  Had a problem... out of memory.


Command line shows the memory increase flag I tried, but it is a flag for nodeJS, and I don't know if grunt is handing-it-on to nodeJS.  I doubt it. 

NodeJS is 512 by default, I hear.  I don't know enough about how the build operates, yet, I suppose.  If someone has a fix for this, I'd be glad to read it and heed it.  :)  thx!

Link to comment
Share on other sites

Yep, but has been fixed. Unfortunately, the index build part needs some memory... We can reduce it but it will hurt the dcumentation search.

Wingnut, if you don't need the search locally, try to remove this line from the grunt file : https://github.com/BabylonJS/Documentation/blob/master/Gruntfile.js#L168

Link to comment
Share on other sites

Oh HELL yeah!  PERFECT!  I have no need for local search... and now I'm down to a 24 second build!  This also eliminates needing to prog a "single md builder", because 24 secs is wonderful!  I can easily wait 24 secs to test the HTML of an md file that I have edited.

Thankya thankya thankya!  I have decent workflow for edits!  YAY!

The server didn't auto-launch, but I'm sure I can adjust that.  I use MarkdownPad2 to edit .md files locally (github flavored).  It has a "view in browser" button.  Perhaps, perhaps, perhaps... I can wedge-into its GUI and add a "save, build, and browse this document" button or .bat... to that editor.  But even if I can't, you just rescued my workflow, T!  Excellent!  Well done.

(Wingy pees a little... from happiness)  :)

It would be nice to have a 'github-clone only the content folder'... to make sure I have fresh .md before I start doing an edit.  I bet THAT can be done, too.  We're rollin', baby!

Update 01 MAR 2016:  Apparently, once you have the docs repo locally cloned, a repeat clone ONLY updates the "changes", and so it's really fast.  (I'm new at this.)  Therefore, there is no reason to try to clone ONLY content/tutorials.  I can do a full re-clone of the docs repo before I start local editing of a .md document. 

I'm using Windows Powershell instead of ConEmu, this time.  I tried to install posh-git, which lead me to try to install psGet and psReadLine.  That was a disaster, errors in profiles, possibly due to using older version of Powershell.  I'm still seeking control-a/c/v cut'n'paste at the powershell prompt.  So far, no joy.

Update 05 MAR 2016:  Hey, there is an almost-tolerable cut'n'paste popup menu on right-click in powershell 2.  Also, I learned today... that there are aliases allowed.  In combo with .bat files (and other scripts), a guy might be able to make this thing tolerable.  Off to work on 'posh' colors and fonts, now, and practice some git things that @RaananW and others recently taught me.  Hide the kids and helmet the dog!

Update 14 MAR 2016:  After a hard-giggin' weekend, and very little git-stuff learned, I;m back at it again.  This page

Update 08 MAR 2016: Check out http://pcottle.github.io/learnGitBranching/   Wow... this thing actually pets the puppy for pooping uncontrollably!  (it is a true "GIT for dummies" thing... really slow and easy).  I love it.

Spent most of today trying to push a branch called testing... from my home computer (via shell)... to my github acct.  Did all the hoopla needed for SSH, which included updating to PowerShell 3, installing psGet and posh-git... so I could get an ssh agent.  I registered my SSH key at Github... did some tests.

Permission denied (publickey)... over and over, while testing the ssh connection (haven't even arrived at PUSH command yet).  *sigh*.  Maybe I'll return to a GUI interface for GitHub, due to days like these.  herf!  Does anyone have any input about what I am doing wrong?  (thx!)  Tomorrow is another day.  I got all night to replace the blood I spilled today.  :)

Update 09 MAR 2016: Yay!  http://urbanproductions.com/wingy/babylon/misc/perm_granted.txt  I needed to ssh-add identities for my three keys (rsa, dsa, and ecdsa).  You can only do that AFTER you turn-on the ssh agent.  (eval `ssh-agent -s` in the bash shell).  Hooray!  Did ya see that line?  'Hi Wingnutt! You've successfully authenticated'.  By golly, I might STILL be able to achieve my life-long dream of being a pusher!  :)

More... Check out THIS log, if you please.   Automated, automated, automated.  The Gods will party in the streets, tonight!  I have a new friend... .bashrc.  Granted, I am causing every launch of bash... to ssh-connect to github.  Likely unnecessary, but knowing that I CAN do that... feels gooood.  I would also like to give an 'attaboy' to the Atom text editor... which is doing me well.  And that ~ thing... OMG what a handy thing THAT is!   Yay!

Update 10 MAR 2016:  Hi. 


A screen-grab of my config files...  powershell.ps1, bashrc, and .logout... also for bash.

Today, I am working to clean-up multiple ssh-agent processes that remain running after I use the X to close powershell/bash.  Plenty of success, after a little web research. 

Of course, the MAIN objective is to test for already-running ssh-agents, and don't launch a new one if it is not needed.  Secondary objective, is to remove the most recent ssh-agent process... no matter HOW "abruptly" you close the powershell session (like with the X button - done right in the middle of a git bash prompt).  Technically, if that powershell X button is hit, we need to do a proper logout from github, we need to do a proper bash .logout, and have powershell do a last-second "Are we ready to close?" -check.  In the above picture's left editor window (the powershell .ps1 file)... we can see how that is done with v3+. 

My docs editing environment gets sweeter by the day.  I still haven't done the push of my local 'testing' branch.  Somewhere, I heard that if the branch doesn't exist on the remote, it auto-creates one called 'testing' on the remote.  In the 1-2 experiments that I have tried so far... that has failed.  The push tests have resulted in good auth-ins, but rejection due to "repo not found".  More to learn.  Keep in mind that I am also trying this push... with the --dry-run flag, which could be having an affect.  Yeah, I know, --dry-run is for girls and wussies.  I'm a proud member of Wussies, Inc.  :) 

Link to comment
Share on other sites

Hey gang!  Docs elders... can you help me ponder the ramifications of removing all numbers from playpen tutorial names? (about 14 docs?)

Also, I would like to change urls like http://www.babylonjs.com/tutorials/04%20-%20Materials/04.png

...into something more like this... http://www.babylonjs.com/tutorials/materials04.png  , as well.

Images such as this... http://urbanproductions.com/wingy/babylon/misc/tut02pic.jpg ...need fresher versions, and could be removed from my buddy's server, too.

I would like to remove all the numbers in the Playpen tutorial names and images.  Picture names such as materials04.png are fine.  I am talking about the other numbers.  (the one's that steal the "fluidity" from the playpen tutorials.)  I would like the playpen tutorials to match/use the "system" that all the other tutorials currently use.

Back in the old days, I tried to match the tutorial number... with the playground's built-in demo numbers... but I think I want to get away from that, now. 

Can the docs elders do this faster and easier, than I can?  I will gladly fix the links in the playpen tutorials themselves... no problem there.  But I am having difficulty in determining all the far-reaching ramifications and workload of this change.  Any help on that... would be greatly appreciated. 

Also note... that I am a bit scared of multi-file PR's, too.  I've read that it is not wise, because github discussions then need to talk about the entire commit, and no one-discussion-per-file can happen.  Still learning.  I suppose the curators would forgive me if I did a multi-file PR that ONLY fixed the bottom link (link to the NEXT in the playpen series) for 14 documents.  The curator could probably see what I was doing (fixing all 'next tutorial' links), and it would be allowed. 

In fact, maybe the 'next tutorial' links should be removed.  Not sure.  Thoughts welcome.

Playpen series 15-19 are already a-ok.  It would also be fine with me... if there was no longer 3 categories of tutorials (playpen, mid-level, advanced).  One giant pile of tutorials would be fine with me... if it's cool with the tribal elders.

And, if this is too much hassle, no sweat... I can cope with it as-is, too.  But I suspect that DK or Temechon can do this entire fix... in under 15 minutes.  That... would be wonderful, and I would gladly give you my dog if you guys did it. :) (thanks)

Link to comment
Share on other sites

Holy cow, that's scary, but done.  I need to do some research.  Maybe that could have been done with 1 PR, but I used 2, one for the json edit, one for the md rename.  Tutorial #1... renamed to Creating_a_Basic_Scene.md.

Wingnut, inside a json file.  Yikes!  It felt like I was trying to remove a bug carcass from the front of a speeding train.  :o:)  Thanks for the help, though.

Link to comment
Share on other sites

Hello guys,

Here is a new feature in the documentation : now when you write a link to a playground (http://www.babylonjs-playground.com), the doc will automatically add a 'eye' icon after it.
By clicking on this icon, an iframe will open and the playground will be displayed. Clicking again on the eye will remove this iframe. You can test it here for example : http://doc.babylonjs.com/tutorials/Parametric_Shapes

You don't have to do anything as a doc writer :)

I hope you will enjoy it!

Link to comment
Share on other sites

  • 4 weeks later...

Hi gang.

Okay, I have been fooling around with git and github for a while, now  (it's still annoying).  There is still one big unsolved question for me:

Does it REQUIRE a pay git account... to do push (to my github bjsdocs fork) from my home?

With ssh connects, I get the classic line...  "You've successfully authenticated, but GitHub does not provide shell access."

Every time I search the web... to seek WTF "does not provide shell access" MEANS... I get unhelpful returns.

Does it mean... "Does not provide shell access for free accounts"?

Other push attempts... using https (with name and password) have returned "Permission Denied" but I could be making a mistake... accidentally pushing to the wrong remote.

IF it IS true... $84 per year for push-from-home perms... that is not so bad.  *shrug*

Currently (with free account)... I can do full BJS docs editing WITHOUT push-from-home.  But, hmm.  Push-from-home opens-up a possibility for a really nice 'automated' system... especially now that I've seen the power of 'watch'.  'Watch' appears to be a "thing" that monitors changes in my home repo, and can DO STUFF when changes are seen - pretty nice.  Auto-stashing, auto-commits, even auto-PR's... all possible with a SAVE from my MarkdownPad2 home editor.  hmm.  Power repo-wranglin', ride 'em cowboy, yeeee ha!

Anyway, if anyone wants to fix my lingering stupidity (teach me more git stuff)... I would be very happy and less stupid.  (thx)

By the way, I'm getting excellent docs build speeds, even WITH search indexing active, lately.  Full docs build at home...  55s, no errors.  A 'watch' rebuild-after-edit... 24s.  SWEEEET!!!

Link to comment
Share on other sites

github manager?  You mean this webby interface?  I do.  That's currently how I do most things.

But, I still maintain a perfect clone repo at my home puter... cuzzzzz...  I sometimes need to do 'builds' so I can run the docs website on my localhost:3000... so I can make sure that the build-generated html for the .md file I edited/created... looks/works nice.  I also need to make sure it has a pretty table of contents (genned by the build). 

When everything looks correct, I visit the bjs-docs web interface and paste-in the doc, commit and pr.  That creates a patch-1 fork for me, and things seem somewhat safe and automatic, but I still get scared.  :/

But, since I DO maintain a near-exact clone at home... maybe it IS worth the money to do further automation of my editing workflow.  But first, I need to make sure that it DOES cost money to push (to my free github acct) from home.  I have not determined if that is correct, yet.

Link to comment
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.


  • Recently Browsing   0 members

    • No registered users viewing this page.
  • Create New...