Cocoa developer documentation site.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
mkdocs-material @ fa74ebc
.gitignore
.gitmodules
.travis.yml
404.html
LICENSE
README.md
build.sh
deploy.sh
mkdocs.yml
requirements.txt

README.md

Build Status

Cocoa Developer Docs

Remote Repositories & Contributing

There are two remote repositories, the public GitHub repo, and the private BitBucket repo. We encourage contributions through the GitHub repository either by creating an issue or fork/pull request.

The private repository is intended for internal documentation on products that have not yet been publicly released.

Cloning Submodules

The mkdocs.yml file is setup to utilize the theme elements from the local folder. This is because we use a modified version of the standard material for mkdocs theme. They are available publicly on GitHub and distributed in this repository as a submodule.

After cloning this repository as you would normally, the submodule folder(s) will at first be empty. Run the following command to update the submodules. Without running this command, you won't be able to build the site.

$ git submodule update --init --recursive

Managing Two Remote Repositories

The GitHub repository is used for GitHub pages hosting as well as the publicly available source. We appreciate any feedback through forks/PR's or issues on the GitHub repository.

The Bitbucket repository is used for internal changes that are not ready for public consumption.

Warning: Be sure you push to the right repository. Here are some helpful commands:

View remote repositories:

$ git remote
$ git remote -v

Set new URL for origin:

$ git remote set-url origin git://bitbucket.org/bitbucket/url/here

Add remote:

$ git remote add [repo alias] [git url]

You may additionally like to change the default push and pull defaults to "nothing". This way you will have to specify the remote alias every time you git push or git pull

$ git config push.default nothing
$ git config pull.default nothing

Building Site and Publishing

This documentation is built with the static site generator, MkDocs. You will need to download MkDocs on your local machine to preview the build before.

Downloading MkDocs

Documentation on how to download MkDocs is best found on the MkDocs website.

We are utilizing a local instance of the Material for MkDocs theme which is stored as the a submodule. If you make any changes to the source you need to rebuild the theme by running npm run build from the mkdocs-material directory

Running Locally

Set your pwd to the top level of this repository and run mkdocs serve.

$ cd your/docs/repo/here
$ mkdocs serve

Deployment

Travis-CI is used to deploy the static site to docs.cocoa.io. While you can deploy with mkdocs-deploy, you should utilize the deployment tools in Travis by making a pull request into the master branch. Developers are restricted from pushing directly to master.

Prior to deployment, deploy the site locally with mkdocs serve.