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.
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
$ 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 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.
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
Set your pwd to the top level of this repository and run
$ cd your/docs/repo/here $ mkdocs serve
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