/cocos-docs

Documentation for Cocos2d-x, Cocos2d-html5 and Cocos Studio

Primary LanguageJavaScriptOtherNOASSERTION

Documentation

This is the Cocos Documentation Repo. It is licensed under the Creative Commons BY-SA license.

You can read these docs online.

This repo builds

  • Cocos docs
  • Installation docs
  • Programmers Guide
  • API-Reference
  • Services, like SDKBOX

Directory layout

  • api-ref/ - API Reference, build.sh does a lot here that is not in this dir.
  • blank.md - a blank page that is used when building print versions
  • build.sh - BASH script that build web and print versions, deploys to staging server
  • catalog/ -
  • cocos/ - docs relating to Cocos
  • deploy.sh - this script deploys the docs to cocos2d-x.org/docs
  • index.md - this is the main landing page, part static, part dynamically created in build.sh
  • installation/ - docs relating to installation on supported platforms
  • LICENSE.md - licensing
  • manual/ -
  • mkdocs.yml - MKDocs configuration
  • programmers-guide/ - The Cocos2d-x Programmers Guide
  • README.md - this file :-)
  • release-notes/ - release notes
  • services/ - docs relating to supported services, like SDKBOX
  • static-pages/ - static pages that we need
  • styling/ - CSS for print version of the Programmers Guide
  • theme/ - custom theme for web version
  • title.md - title page
  • tutorial/ - Tutorials

What do you need to build for OS X?

How to run/test these docs

  • cd <where you cloned this repo>
  • run build.sh --all
  • run mkdocs serve

Any changes made while mkdocs serve is running are automatically rebuilt.

How to build for deployment

  • cd <where you cloned this repo>
  • run build.sh --all

Content is built in docs and deployed to site. This script also builds the ePub and PDF versions as well as deploys out to our staging server and http://www.cocos2d-x.org/docs

API-Ref

The legacy API-Refs are now downloaded and deployed as needed. No need for us to store these in GitHub as they don't change.

  • cd <where you cloned this repo>
  • run build.sh --legacyapi

When contributing

  • make sure to break lines at 80 columns.
  • edit via a pull request. Please do not edit chapters and push directly.
  • if you are creating a new document, please don't make it feel and sound like an API Reference. Please tell a story about your content. We want to make this engage the user. If in doubt: read Chapter 2 and notice it feels like a chapter in a book.
  • contact me via e-mail or on the forums to discuss what you want to add, edit, etc.

Additional layout notes

  • each chapter has a markdown file and 3 image directories associated with it.
  • the image directories are -web, -print and -img. -web is properly sized images for displaying on the web. print is properly sized images for displaying in the epub and pdf. -img is were to put the original images (also displayed when viewing from GitHub).
  • the build.sh script does copying and renaming of directories during the build process since the markdown files expects files at a specific path. Take a look.
  • if a chapter does not have any images there is no need to create directories for it.

Supporting multiple languages (cpp, js, lua)

To support C++, JavaScript, (and technically Lua when ready), you can easily embed div elements and put the content for that language in between:

Example for C++:

<div class="langs">
<ul>
  <li><a href="#" id="tab-cpp">C++</a></li>
  <li><a href="#" id="tab-js">Javascript</a></li>
</ul>
</div>
<div class="tab-cpp tab_content">

some content that is c++ specific.....


more c++ specific content....

auto mySprite = Sprite::create("mysprite.png");
even more c++ specific content....
  </div>

Example for Javascript:

  <div class="tab-js tab_content">

some javascript specific content...

var mySprite = Sprite.create("mysprite.png");
more javascript content....

  </div>

Note: there is a blank line after the opening div and before the closing div elements. This is a markdown requirement or else it will not render properly.

Note: Also notice that the div elements are indented by a single tab. This is also a markdown requirement or else the text will not render properly.

If you find an error