cocoapods / cocoadocs.org

Static generator for CocoaDocs.org

CocoaDocs.org

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 [email protected]: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:

• Orta Therox - Design & Code
• Sam Giddins -Admin & Code
• Kyle Fuller - Admin & Code
• Delisa Mason - Docstat gem
• Clay Allsopp - README Complexity gem
• Ash Furrow - Javascript & Ruby assistance
• Boris Bugling - Boring legwork on templates

cocoadocs.org's Issues

Order of dependencies isn't semantic

No favicon

Dash docset icon is not Retina-ready

Dash docset icon is not Retina-ready. Sorry for spamming you with issues!

Private classes listed in documentation

It seems that every class in the library project has a docs page generated. Would be better if just stuff declared in a public header file gets documented.

Example: http://cocoadocs.org/docsets/Slash/0.1/
Project/podspec: https://github.com/chrisdevereux/Slash

SLSMarkupParser is the only public class in this library. It's a bit confusing having all the other ones listed.

Not sure how this plays with libraries that expose different classes depending on the target platform. Maybe generate a different set of docs for each?

Docsets appear in homepage but are 404s

list from @MaxGabriel

ELCTextFieldCell http://cocoadocs.org/docsets/ELCTextFieldCell/
Heyzap http://cocoadocs.org/docsets/Heyzap/
ELCImagePickerController http://cocoadocs.org/docsets/ELCImagePickerController/
EasyTableView http://cocoadocs.org/docsets/EasyTableView/
MSLabel http://cocoadocs.org/docsets/MSLabel/
REKit http://cocoadocs.org/docsets/REKit/

Support Private Pod Repos

I'd like to repurpose this to spin up documentation on some internal libraries we are tracking internally, but the current script is a little to specific for the public repo.

Would like to see some hooks to make it more generic.

Library spec has broken links: QR-Code-Encoder-for-Objective-C

State of Dash integration

Is the Dash integration ready for primetime? I noticed only libraries that start with A show the Dash button and the regeneration doesn't seem to have progressed to B. Anyways, my question is: should I direct users to CocoaDocs.org in the next Dash update (which will come in about 8-10 days)?

Dash external resources (e.g. images)

Some docsets (e.g. http://cocoadocs.org/docsets/AFNetworking/1.2.0/) include external resources (the AFNetworking logo).

I think it would be unfeasible for you to parse all documentation pages and download online resources for offline use somehow.

In the next update of Dash, I will allow the loading of online resources. However, please try to avoid using online resources yourself as it will increase load time unnecessarily and would make the docset not work while offline.

So, close this issue, it will get fixed in the next update of Dash.

Overflowing text on sidebar

http://cocoadocs.org/docsets/MagicalRecord/2.1/

Could do with an ellipsis

the keyboard up / down should scroll the page to show the selected element

URL Anchors break Link

See http://cocoadocs.org/docsets/FDWKit/0.0.1/Classes/FDWClient.html. URLs dont include the anchors.

Dash integration is broken

Dash version: latest from App Store
Steps to reproduce:

1. Goto cocoadocs.org, choose any library
2. Press Dash icon in right upper conner.
3. Dash window will be opened with new docset available for download.
4. Press download button
   Result: Dash will fail to download docset
   If you copy url from error description such as http://cocoadocs.org/docsets/ELCTextFieldCell/ELCTextFieldCell.xml, you'll see that url to docset contains double slash (http://cocoadocs.org//docsets/ELCTextFieldCell/ELCTextFieldCell.tgz). That's the reason Dash unable to download docs. If you delete double slash everything works fine.

Going to a project without the version should redirect to the latest documented version

http://cocoadocs.org/docsets/Objection/ -> http://cocoadocs.org/docsets/Objection/0.15.1/

Use any settings in from the Podspec which look safe.

A good example
Example: http://cocoadocs.org/docsets/MapBox/1.0.3/

https://github.com/mapbox/mapbox-ios-sdk/blob/release/MapBox.podspec#L35-L69

Docsets & Docset feeds

Currently disabled to save bandwidth, they should be easily accessible in that weird xar format.

TMCache shows up in autocomplete but docs page is 404

http://cocoadocs.org/?q=tmcache
http://cocoadocs.org/docsets/TMCache/

not seeing past versions in the drop downs

http://cocoadocs.org/docsets/AFNetworking/1.2.1/

but http://cocoadocs.org/docsets/AFNetworking/1.0/ exists and is parsed.

Can anything be done to improve SEO on docs pages?

Sidebar still there when the content has moved to the bottom

reduce the size of the window here: http://cocoadocs.org/docsets/MagicalRecord/2.1/

Stop ignoring the podfile's opinion on how it should be appledoc'd

Not polite.

`rake setup` doesn't prompt for s3 access key

When running rake setup, the process hangs on the 'Configuring s3cmd' step. When I run s3cmd --configure manually, it correctly prompts for S3 access keys and such.

Xcode failing to download docsets

I've just found that attempting to install docsets using the atom feed results in an error as shown in the attached screen shot. I've had this with MagicalRecord, StackMob, & UIKeyChainStore.

Cheers, Pedro

Documentation is not generated for new library version

Hi!

Recently, about a week ago, i updated one of the frameworks i'm maintaining, but cocoadocs still didn't update documentation for it.

Here's merged pull request
CocoaPods/Specs#2667

New tag:
https://github.com/DenHeadless/DTTableViewManager/tree/1.1.0

I thought it is a browser cache issue, but clearing it did not help. It seems there's only 1.0.0 tag present on cocoadocs.org.

Images and links that in readmes presume they are on github

Seems reasonable. We should check that anything which is a relative url should get a prefix for the github repo.

Improve Github Integration

• Make the github logos alpha hidden, not display none so you have a clue they're there.
• Make the "Declared in DFPExtras.h" link to a github search in the project for the file. Or ideally link directly or the file. ( This is hard due to branches, but maybe could work. )

/cc @ursachec

up / down arrows are not always working in safari

Dash & Xcode hover popover closing when it should not

See http://cl.ly/0r21381t2103, that's in Google Chrome. I've also tested in Safari and it happens as well. Same thing happens to the Xcode one.

As far as I can tell there's a 1px gap between the popover and the icon which causes the popover to close.

Documentation browser does not display well macro-decorated properties

This issue has been first created by mistake on the CocoaPods repo: CocoaPods/CocoaPods#1204.

Reopening it here as a reminder.

Xcode [X] doesn't allow downloading of docsets anymore

properties are empty in class view

http://cocoadocs.org/docsets/MMDrawerController/0.0.1/Classes/MMDrawerController.html

Add the about information to the home page

add support for Apple's libraries in homepage search

I've heard AVFoundation is a litmus test.

Private headers are getting added

  appledoc --project-name MSActiveConfig --project-company 'Javier Soto' --index-desc resources/overwritten_index.html --company-id com.cocoadocs.msactiveconfig --project-version 1.0.1 --no-install-docset --templates ./appledoc_templates --verbose 5 --keep-intermediate-files --create-html --publish-docset --docset-feed-url http://cocoadocs.org/docsets/MSActiveConfig/xcode-docset.atom --docset-atom-filename xcode-docset.atom --docset-package-url http://cocoadocs.org/docsets/MSActiveConfig/docset.xar --docset-package-filename docset --docset-fallback-url http://cocoadocs.org/docsets/MSActiveConfig --docset-feed-name MSActiveConfig --keep-undocumented-objects --keep-undocumented-members --search-undocumented-doc --output 
 /Users/orta/spiel/html/cocoadocs/activity/docsets/MSActiveConfig/1.0.1/ 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfig\+Private.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfig.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfigConfigurationState\+MSLazyLoadedState.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfigConfigurationState\+Private.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfigConfigurationState.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfigDownloader.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfigListener.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfigMutableConfigurationState.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfigSection\+Private.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfigSection.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSActiveConfigStore.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSJSONURLRequestActiveConfigDownloader.h 
 /Users/orta/spiel/html/cocoadocs/activity/download/MSActiveConfig/1.0.1/MSActiveConfig/MSActiveConfig/Classes/MSUserDefaultsActiveConfigStore.h 

Dash integration not working

for a lot of pods.

example:

iCarousel -> http://cocoadocs.org/docsets/iCarousel/iCarousel.xml
but http://cocoadocs.org//docsets/iCarousel/iCarousel.tgz point to nothing.

MagicalRecord -> http://cocoadocs.org/docsets/MagicalRecord/MagicalRecord.xml
but http://cocoadocs.org//docsets/MagicalRecord/MagicalRecord.tgz point to nothing.

etc.

others: NUI, PSTCollectionView, ReactiveCocoa.

Thanks

MagicalRecord 404 error

http://cocoadocs.org/docsets/MagicalRecord/ gives 404

typo in description

The description refers to cocoadoc.org rather than cocoadocs.org; missing an s on the domain, I believe.

CocoaDocs does not support subspecs source_files

Looking at the docs generated for one of my projects, I see some private methods listed at the bottom that are not included in the header file.

Perhaps we could provide more deeply supported integration with CocoaPods, and allow a new parameter in the podspec itself to point to an AppleDoc plist within the repo (Since AppleDoc supports providing it a plist instead of a command line list of arguements). That would let developers tune what information should be documented by CocoaDocs.

Thoughts? cc: @alloy

UPDATE:
Renaming issue to match the problem.

Can't easily get to github from a ≠pod page

Dash CSS issue

Some CSS files are still not available locally:

<link rel="stylesheet" type="text/css" media="print" href="http://cocoadocs.org/assets/appledoc_print.css" />
<link rel="stylesheet" type="text/css" href="http://cocoadocs.org/assets/appledoc_gfm.css" />

DocSets generated online doesn't include all assets

Documentation sets generated using the provided .atom link on a given page e.g. AFIncrementalStore are missing the following:

• assets/appledoc_setup.js
• assets/img/xcode_tiny.png
• assets/img/dash_tiny.png
• ../metadata.json

Xcode 4.6.3 currently doesn't seem to care, but future versions of Xcode may display a modal dialog for each missing asset whenever an affected documentation set is viewed.

Switch my email with new issue button

Emails get lost, I look here for issues

GRButtons 0.0.1

404 for http://cocoadocs.org/docsets/GRButtons/0.0.1
Bye :)

StackMob v 2.0.0 404 error

http://cocoadocs.org/docsets/StackMob/2.0.0 gives a 404 error.
I'll report this on StackMob's support pages as well.

The docs for StackMobPush
http://cocoadocs.org/docsets/StackMobPush/1.0.2/
do appear.

latest deploy has missing readmes index files

CocoaDocs is the name

There should be no references to "Cocoadocs"

add a command argument for a specific spec name to test

ruby app.rb TMCache to do TMCache

404

Was playing around and found this: http://cocoadocs.org/docsets/xmlrpc/

I also found a few others (might be related to docsets that start with X? I don't know):
http://cocoadocs.org/docsets/XPCKit/
http://cocoadocs.org/docsets/XingSDK/
http://cocoadocs.org/docsets/XYPieChart/
http://cocoadocs.org/docsets/Xbox360ControllerManager/

Seems to happen with docsets that start with Y and Z as well, so it might be related to the docsets that have been indexed/generated last.

Link to @orta on homepage goes to CocoaPods Twitter account

Link goes to http://twitter.com/cocoapods instead of http://twitter.com/orta

Default doc link points to older version

Looking at the update today, I see that CocoaDocs is pointed to the older version:

This url (http://cocoadocs.org/docsets/MMDrawerController/) will auto redirect to http://cocoadocs.org/docsets/MMDrawerController/0.0.1/ instead of the newer http://cocoadocs.org/docsets/MMDrawerController/0.0.2/