This repository has been archived by the owner. It is now read-only.
Static generator for CocoaDocs.org
Clone or download
Latest commit b18fad1 Mar 21, 2018
Permalink
Failed to load latest commit information.
.github Adds the new IP for the CP CocoaDocs docs Dec 15, 2017
.vscode Add support for custom README locations Jan 31, 2017
appledoc_templates Use HTTPS when linking to CocoaPods Apr 5, 2015
classes Handle the README/CHANGELOG locations correctly Nov 4, 2017
resources remove unused assets, update favicon, added local css assets May 10, 2014
spec Further escape pod names Jul 2, 2016
vendor Update headliner to correctly change the title Nov 17, 2015
views Use AWS Hosted Search Jul 5, 2017
.env.sample Make the pinger submit stats data Jul 17, 2015
.gitignore Don't try upload a changelog if it doesn't exist May 20, 2017
.ruby-version Update to ruby 2.3.1 (which is already baked into BB's VMs) Jun 12, 2017
.travis.yml maybe fix travis Nov 28, 2016
Gemfile Update readme-score dep to use https url Dec 14, 2017
Gemfile.lock Update readme-score dep to use https url Dec 14, 2017
LICENSE split server & docs, added license & improved readme May 18, 2014
Procfile use a shell loop Mar 24, 2015
README.md Update README.md Mar 21, 2018
Rakefile Adds the new IP for the CP CocoaDocs docs Dec 15, 2017
cocoadocs.rb Remove the `download_badge` (Deprecated in 0.9.0) Nov 9, 2017
cocoapods-simple.rb Fixes the location of the uploaded CHANGELOG Nov 14, 2017
misc.rb add a script to run each doc Jul 1, 2014
ping.rb Sigh, just use HTTParty for the sending to status Jul 17, 2015
server.rb Update the CocoaPods server to not run the documentation aspects Nov 4, 2017
webpages.rb Fixed a bunch more cases of improperly escaped paths, leading to whit… Oct 15, 2014

README.md

CocoaDocs.org

Build Status

State of CocoaDocs

CocoaDocs was deprecated back in early 2015 and now has a replacement for the CocoaPods-specific infrastructure. If you've come to get help about a CocoaDocs page, I'm afraid it doesn't exist anymore.

Getting Help

If you're wanting to debug your own library, please consult the ISSUE_TEMPLATE.md.

What is CocoaDocs

CocoaDocs is essentially 2 tools, one is a script for generating complex appledoc templates and the other is a server aspect for reacting to webhook notifications.

Installation instructions

  1. git clone git@github.com:CocoaPods/cocoadocs.org.git
  2. cd cocoadocs.org
  3. bundle install
  4. bundle exec rake install_tools

The install_tools tasks will install the additional tools required for CocoaDocs to work:

* [cloc](https://github.com/AlDanial/cloc)
* [appledoc](https://github.com/tomaz/appledoc)
* [carthage](https://github.com/Carthage/Carthage)
* [AWS' official CLI tool](https://aws.amazon.com/cli/)

How it works for the 99% use cases:

CocoaDocs receives webhook notifications from the CocoaPods/Specs repo on GitHub whenever a CocoaPod is updated.

A Swift Pod will create documentation using Jazzy. If this fails, perhaps due to new Swift version support, than it will fall back to Objective-C. An Objective-C Pod will use Appledoc to parse your library.

If you have a Swift library and it's only showing Objective-C classes (or no classes) then Jazzy has crashed on your library, we'd recommend testing that out locally.

What control do I have over CocoaDocs as a library author?
  • For Objective-C projects, you have the ability to edit the styling of CocoaDocs for your own libraries to give some personal branding. This is done by adding a .cocoadocs.yml file to the root of your library, which overwrite these properties:

    highlight-font: '"GT Walsheim", "gt_walsheim_regular", "Avant Garde Gothic ITCW01Dm", "Avant Garde", "Helvetica Neue", "Arial"'
    
    body: '"Helvetica Neue", "Arial", san-serif'
    code: '"Monaco", "Menlo", "Consolas", "Courier New", monospace'
    
    highlight-color: '#ED0015'
    highlight-dark-color: '#A90010'
    
    darker-color: '#C6B7B2'
    darker-dark-color: '#A8A8A8'
    
    background-color: '#F2F2F2'
    alt-link-color: '#B7233F'
    warning-color: '#B80E3D'

    All defaults are stored in this config file for you to overwite.

  • You can find an example of styling at ARAnalytics's .cocoadocs.yml

  • You can change the location of your readme with readme: path/to/README.md in your .cocoadocs.yml.

  • You can add your own documentation guides, either from remote markdown files or from files locally inside the library. CocoaDocs will automatically convert github wiki pages to the markdown behind it. These only work on Objective-C codebases.

    additional_guides:
      - https://github.com/magicalpanda/MagicalRecord/wiki/Installation
      - https://github.com/CocoaPods/CocoaPods/wiki/A-pod-specification
      - docs/Getting_started.md
  • If you host your own documentation, and/or just prefer to not use CocoaDocs you can use the documentation_url reference in your Podspec.

Previewing my library in CocoaDocs

First, clone this repo: git clone https://github.com/CocoaPods/cocoadocs.org then run bundle install and then run bundle exec rake install_tools to get all pre-requisite apps set up.

To preview your library run:

bundle exec ./cocoadocs.rb preview ARAnalytics

This will get the master version of your library and run it through CocoaDocs, then open the resulting folder, you can open the index.html in a web browser to preview locally.

CocoaDocs Admin

The CocoaPods' CocoaDocs server is hosted on macminicolo.net provided by Button. We use RSA public keys to log in. You'll have to get your id_rsa.pub to an existing admin ( currently orta /segiddins ) to get access.

SSH access is automated via the Rakefile:

  • bundle exec rake deploy - will log in via SSH, stop the API server, update it and then bring the server back up.

  • bundle exec rake doc["pod_name"] - will log in via SSH, and run a re-doc for a pod. Similar to the redeploy API, but you can see the logs.

Thanks!

The creation of CocoaDocs v2 has been made possible with help from the following: