Documentation not generated #310

Closed
hartbit opened this Issue Jun 7, 2012 · 24 comments

3 participants

@hartbit

My appledoc documentation is not generated when adding my project as a dependency.
Because of issue #304, I can't lint it completely, but --quick returns no errors:

Pod::Spec.new do |s|
  s.name      = 'Fuji'
  s.version   = '0.0.1'
  s.license   = { :type => 'Simplified BSD', :file => 'LICENSE.md' }
  s.summary   = 'An iOS game development framework with a clean and extensible component-base design.'
  s.homepage  = 'http://TrahDivad.github.com/Fuji/'
  s.author    = { 'David Hart' => 'david@hart-dev.com' }
  s.source    = { :git => 'https://github.com/TrahDivad/Fuji.git', :commit => '141a3904c46a1a35dde525917e28dd44c1122067' }

  s.platform      = :ios, '5.0'
  s.source_files  = 'Fuji/Sources/**/*.{h,m}'
  s.requires_arc  = true
  s.frameworks    = ['Foundation', 'CoreGraphics', 'OpenGLES', 'GLKit', 'UIKit']

  s.documentation = { :appledoc => [
    '--product-name', s.name,
    '--project-version', s.version,
    '--project-company', 'hart[dev]',
    '--company-id', 'com.hart-dev']}
end
@alloy
CocoaPods member

If Pods/Fuji already exists, then the docs will not be generated. Could that be the issue?

@hartbit

Nope, I made sure I deleted the whole Pods folder. Where is the documentation supposed to be generated?

@alloy
CocoaPods member

Oh wait, you’re right, if it exists in ~/Library/Developer/Shared/Documentation/DocSets/ it will not be generated.

@alloy alloy closed this Jun 7, 2012
@alloy alloy reopened this Jun 7, 2012
@hartbit

Nope, nothing in there.

@alloy
CocoaPods member

Hmm. If you run pod install with the --verbose option, does it say anything related to documentation?

@hartbit

No.

Davids-iMac:TEST david$ pod install --verbose

Updating Spec Repositories

Updating spec repo `master'
   $ /usr/bin/git pull
   Already up-to-date.

Resolving dependencies of: /Users/david/Desktop/TEST/Podfile

Resolving dependencies for target `default' (iOS)
  - Fuji (from `https://github.com/TrahDivad/Fuji')
  * Pre-downloading: 'Fuji'
-> Cloning git repo
-> Updating cache git repo (/Users/david/Library/Caches/CocoaPods/Git/cd5a5d2c291851599781867ff7496737afae2912)
   $ /usr/bin/git reset --hard HEAD
   HEAD is now at ec15797 Updated podspec.
   $ /usr/bin/git clean -d -x -f
   $ /usr/bin/git pull
   Already up-to-date.
   $ /usr/bin/git clone '/Users/david/Library/Caches/CocoaPods/Git/cd5a5d2c291851599781867ff7496737afae2912' '/Users/david/Desktop/TEST/Pods/Fuji'
   Cloning into '/Users/david/Desktop/TEST/Pods/Fuji'...
   done.

Installing dependencies

-> Using Fuji (0.0.1)

Generating support files

- Generating xcconfig file at `/Users/david/Desktop/TEST/Pods/Pods.xcconfig'
- Generating prefix header at `/Users/david/Desktop/TEST/Pods/Pods-prefix.pch'
- Generating copy resources script at `/Users/david/Desktop/TEST/Pods/Pods-resources.sh'
- Running post install hooks
- Writing Xcode project file to `/Users/david/Desktop/TEST/Pods/Pods.xcodeproj'

And in case you are wondering:

Davids-iMac:TEST david$ pod --version
0.6.0.rc2
@fabiopelosin
CocoaPods member

Means that the pod is not being installed, so no doc. Can you delete the pods folder and do the report again?

-> Using Fuji (0.0.1)

As a library maintainer, is ti something that you value being able to customize the documentation? I think that the defaults are good enough and I that removing the documentation attribute would keep the specs dry.

@fabiopelosin
CocoaPods member

Oh, sorry, I've missed it. When a pod is pre-downloaded the documentation is not installed. Can you try to define the podspec inline in the podfile?

@alloy
CocoaPods member

When a pod is pre-downloaded the documentation is not installed.

@irrationalfab Can you elaborate on why that is?

@hartbit

@irrationalfab Indeed, defining the podspec inline does try to install the documentation, but it then crashes:

Stack

   CocoaPods : 0.6.0.rc2
        Ruby : ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-darwin11.4.0]
    RubyGems : 1.8.24
        Host : Mac OS X 10.7.4 (11E53)
       Xcode : 4.3.2 (4E2002)
Ruby lib dir : /Users/david/.rvm/rubies/ruby-1.9.3-p194/lib
Repositories : master - git://github.com/CocoaPods/Specs.git @ 8a4da897e71f80e8f86a6d1f7a11b0ce9a01ddc5

Podfile

platform :ios

dependency 'Fuji', :podspec => 'https://raw.github.com/TrahDivad/Fuji/master/Fuji.podspec'

Error

undefined method `empty?' for #<Pod::Version "0.0.1">
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/escape-0.0.4/lib/escape.rb:66:in `shell_single_word'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/escape-0.0.4/lib/escape.rb:53:in `block in shell_command'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/escape-0.0.4/lib/escape.rb:53:in `map'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/escape-0.0.4/lib/escape.rb:53:in `shell_command'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/generator/documentation.rb:87:in `block in generate'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/local_pod.rb:60:in `chdir'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/local_pod.rb:60:in `chdir'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/generator/documentation.rb:86:in `generate'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/installer.rb:71:in `generate_docs'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/installer.rb:60:in `block in install_dependencies!'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/installer.rb:48:in `each'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/installer.rb:48:in `install_dependencies!'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/installer.rb:84:in `install!'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/command/install.rb:53:in `run'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/command.rb:69:in `run'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/bin/pod:12:in `<top (required)>'
/Users/david/.rvm/gems/ruby-1.9.3-p194/bin/pod:19:in `load'
/Users/david/.rvm/gems/ruby-1.9.3-p194/bin/pod:19:in `<main>'
/Users/david/.rvm/gems/ruby-1.9.3-p194/bin/ruby_noexec_wrapper:14:in `eval'
/Users/david/.rvm/gems/ruby-1.9.3-p194/bin/ruby_noexec_wrapper:14:in `<main>'
@hartbit

As a library maintainer, is ti something that you value being able to customize the documentation? I think that the defaults are good enough and I that removing the documentation attribute would keep the specs dry.

Are you talking about customizing the appledoc settings? Well, the reason I started doing it is because CocoaPods appends the version of the library in the --product-name setting instead of using the --product-version. I find it cleaner that way. But in general, appledoc has many settings that I will probably want to use, so yes, I like to customize the settings.

@fabiopelosin
CocoaPods member

@alloy When a pod is installed from an external source it skips the normal installation process as the folder already exists. Imo, this is an area where we can improve, but it is better to do it after implementing the Podfile.lock logic.

@fabiopelosin
CocoaPods member

@irrationalfab Indeed, fining the podspec inline does try to install the documentation, but it then crashes:

And I guess that it works if you remove the docs settings... right?

Are you talking about customizing the appledoc settings? Well, the reason I started doing it is because CocoaPods appends the version of the library in the --product-name setting instead of using the --product-version.

It is done that way so docs for different versions can coexist. Even more importa, is that it allows us to skip the regeneration of the doc if the file exists as docs for a given version should be immutable (excluding enhancements in the CP settings).

@fabiopelosin
CocoaPods member

This fixes it:

    '--project-name', s.name,
    '--project-version', s.version.to_s,
@hartbit

And I guess that it works if you remove the docs settings... right?

What should that look like?

s.documentation = :appledoc

Because that is giving me a new error:

can't convert Symbol into Integer
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/generator/documentation.rb:53:in `[]'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/generator/documentation.rb:53:in `spec_appledoc_options'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/generator/documentation.rb:70:in `appledoc_options'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/generator/documentation.rb:78:in `generate'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/installer.rb:71:in `generate_docs'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/installer.rb:60:in `block in install_dependencies!'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/installer.rb:48:in `each'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/installer.rb:48:in `install_dependencies!'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/installer.rb:84:in `install!'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/command/install.rb:53:in `run'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/lib/cocoapods/command.rb:69:in `run'
/Users/david/.rvm/gems/ruby-1.9.3-p194/gems/cocoapods-0.6.0.rc2/bin/pod:12:in `<top (required)>'
/Users/david/.rvm/gems/ruby-1.9.3-p194/bin/pod:19:in `load'
/Users/david/.rvm/gems/ruby-1.9.3-p194/bin/pod:19:in `<main>'
/Users/david/.rvm/gems/ruby-1.9.3-p194/bin/ruby_noexec_wrapper:14:in `eval'
/Users/david/.rvm/gems/ruby-1.9.3-p194/bin/ruby_noexec_wrapper:14:in `<main>'
@fabiopelosin
CocoaPods member

What should that look like?

I meant not to specify s.documentation = (to be clear, to remove the whole thing).

@alloy
CocoaPods member

@alloy When a pod is installed from an external source it skips the normal installation process as the folder already exists. Imo, this is an area where we can improve, but it is better to do it after implementing the Podfile.lock logic.

Gotcha. Sounds fair enough.

@hartbit

Works now! But is it CocoaPods that is adding my README.md to the documentation? I would prefer that not be the case, but i can't find where it's doing it in documentation.rb

@fabiopelosin
CocoaPods member

@alloy I've opened a ticket about it.

@fabiopelosin
CocoaPods member

Yes it is CocoaPods documentation.rb#L69.

I think that if you override the option it will not add it anymore.

@hartbit

Defining ['--index-desc', ' '] worked! Thanks a lot for your time.

@fabiopelosin
CocoaPods member

Btw, if you are removing the index file because of the codeblocks removing the language after ``` will fix it. It is a known issue (#289).

@hartbit

Nice to know! But no, that's not the case. I prefer to keep the documentation as a pure reference manual, and have the README on GitHub contain a more Getting Started - Installation kind of documentation.

@fabiopelosin
CocoaPods member

It's your choice :-)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment