Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Add documentation and improved licensing fields to podspec #149

Closed
fabiopelosin opened this Issue · 30 comments

2 participants

@fabiopelosin
Owner

I'm suggesting to add this simple changes to spec.rb without introducing any new logic at the moment.

Documentation

Adding a new field for pointing to the Atom link of the documentation set of the Pod. Something like:

s.documentation = 'http://zwaldowski.github.com/BlocksKit/com.dizzytechnology.BlocksKit.atom

Then in the future it would be nice if pod install would add the documentation set to Xcode according to an user preference. appledoc adds the local documentation by compying it and running the following script:

tell application "Xcode"
load documentation set with path #path#
end tell

I guess that the script could be easily modified to add the atom link.

Licensing

Currently the podspec only specifies the kind of licence. It would be also nice to have a pointer to the license file itself. For example:

s.license_text = 'LICENSE'

In some cases like the ( facebook-ios-sdk)[https://github.com/facebook/facebook-ios-sdk] application a single license file is not provided. In that case it could be useful to specify the lines of a file containing the license. Something like:

s.license_text = 'src/FBConnect.h'
s.license_text_lines = '1..15'
@fabiopelosin
Owner

The licensing suggestion arises from the need (that I would guess it is shared by many developers) to generate programmatically the attributions/acknowledgements for an app.

If this information is available it is possible to do something like:

post_install do |installer|
   installer.build_specifications.each do |spec|
       # add spec.license_text to a plist
   end
end

Inspired by http://stackoverflow.com/questions/6428353/best-way-to-add-license-section-to-ios-settings-bundle.

@alloy
Owner

The documentation attribute seems like a good idea, better to start collecting those ASAP. However, I think it should be possible to also specify non-atom URLs, which would then be ignored once we add them to Xcode. (Btw in the future I want it to be possible to generate documentation ourselves, when we install a Pod.)

I had my doubts before about the license_text addition, but that last argument I like pretty much.

Will you submit a patch for this? If so, please also add them to the stub podspec with some explanation.

@fabiopelosin
Owner

Please review the code because I couldn't test it. I'm having some troubles setting up the dev environment. Rake fails installs a Pod directly from its repo test and if I generate the gem i have an error on pod install.

Documentation

Regarding documentation I've read #50 and some podspec ideas mentioning appledoc. Here are my two cents:

  1. support documentation brewing with appledoc
    • It can get bit hairy because it would be necessary to keep track of additional information in the pod spec to generate the documentation. At minimun it would be required to keep track of an additional company identifier.
    • Alternatively, pods that would like to provide documentation could add an AppledocSettings.plist file.
    • Advantages
      • one can have the documentation built for it's exact pod version.
    • Disadvantages
      • different projects using different versions of a pod would override the documentation in Xcode on pod install.
      • increased maintenance of the specs.
      • in the future there could emerge different/better tools compared to appledoc that would have to maintained.
  2. only atom documentation attribute.
    • the human readable documentation can be accessed from the home page of the pod.
    • leaves the door open for a web app indexing the documentation of each version of a pod in a repo if considered useful.
    • very simple and easy to maintain. It would be necessary just to add the link to Xcode.
    • can be called on pod install
  3. documentation_atom and documentation_html attributes.
    • Like n.2 but also providing a nice link to list the docs in cocoapods.org and pod search.
  4. atom or human readable documentation attribute.
    • it is like n.3 but with less attributes to maintain on specs and more logic to handle them.

Personally, I prefer n.2. I think that the link to the home page is enough to access html documentation and that more granular handling of documentation is outside the scope of cocoapods. Publishing with appledoc is quite easy and the files can be hosted directly on GitHub like blockskit does. Although the more I think about it the more i realize that n.3 could make sense.

Please tell me what to do and I'll change the files accordingly.

Licensing

For the lines range i ended up with a format like [int]..[int] that according to this stackOverflow post should be easily parseable in ruby.

@alloy
Owner

Please review the code because I couldn't test it. I'm having some troubles setting up the dev environment. Rake fails installs a Pod directly from its repo test and if I generate the gem i have an error on pod install.

Yeah the master branch is currently in flux. If they run, but with some failures, then just make sure you don't introduce any new ones :)

Support documentation brewing:

Most issues would be solved by not assuming it would be appledoc, but simply a field that contains a command to execute. E.g.:

s.documentation_script = %{appledoc
--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ./doc
--ignore Common
--ignore .m}

different projects using different versions of a pod would override the documentation in Xcode on

Ok, that is indeed a problem, hrmm.

On the other hand, I don’t expect many people will switch between projects that use the same pod (but different versions) on a daily basis, so it might not be a real issue.

I do really like the ability to have the docs for exactly the version I’m using.

Although the more I think about it the more i realize that n.3 could make sense.

I think it should be n.3, but how about a slight variation? One attribute, but not much more logic.

This would add it to Xcode:

s.documentation :atom => 'ATOM URL'

This would open it in a browser:

s.documentation :html => 'HTML URL'

Licensing

I think it might be better to do the license attribute with an options hash too.

The license name with the relevant text:

s.license = 'MIT', :text => 'Permission is hereby granted ...'

The license name and the name of the file that contains the license text, relative to the Pod's root:

s.license = 'MIT', :file => 'LICENSE'

The license name and the name of the file that contains the license text, but limited to the given range:

s.license = 'MIT', :file => 'LICENSE', :range => 1..15

(Note that in this case I used a Ruby Range literal, we don’t need to parse a string.)

@alloy
Owner

Actually, documentation_script should then probably also be used as:

s.documentation :script => 'appledoc ...'
@fabiopelosin
Owner

Good points this is a much cleaner approach!

Documentation script

I replaced the script with s.documentation[:appledoc] and s.documentation[:options]. Supporting a new documentation engine would be really easy because the options are still specified in the pods and but the podspec is prevented from triggering the execution of an arbitrary executable or script.

Documentation options

For the documentation i took inspiration from Ruby Gems and ended up with the following template. It looks like the %{} syntax would carry the new lines and the indentation. An alternative could be to use %{} and convert blanks to a single space, yet I don't know if some blanks like a new line is useful for some options.

s.documentation[:appledoc]  = true
s.documentation[:options]   <<  '--project-name' << '#{@name}' <<
                                '--project-company' << '"Company Name"' <<
                                '--company-id' << 'com.company' <<
                                '--output' << './doc' <<
                                '--ignore' << 'Common' <<
                                '--ignore' << '.m'

Another importan point is that I excluded the path from s.documentation[:options] stating that appledoc will be run on the files specified in s.source_file. Is it reasonable?

Licensing

If I am not missing something I had to use s.license_text[:file] s.license_text[:range] s.license_text[:text]. If I convert s.license to a hash it would break the compatibility with all existing pods. I encouraged the link to license file that is directly maintained by the pod owned.

@alloy
Owner

I replaced the script with s.documentation[:appledoc] and s.documentation[:options]. Supporting a new documentation engine would be really easy because the options are still specified in the pods and but the podspec is prevented from triggering the execution of an arbitrary executable or script.

Very good point!

Ok, so would the idea be that we keep a list of sanctioned doc tools and if it's one of those then execute the tool directly (i.e. not in a shell) so that the options can't also inject commands?

For the documentation i took inspiration from Ruby Gems and ended up with the following template. It looks like the %{} syntax would carry the new lines and the indentation. An alternative could be to use %{} and convert blanks to a single space, yet I don't know if some blanks like a new line is useful for some options.

I think it might be better to specify an array of options. This way we don’t have to split the options ourselves before running the tool. (Ruby 1.9 contains a lib called shellwords which can do this, but we have to support Ruby 1.8 which doesn’t have this lib.)

Finally, I made a mistake in my previous examples which you referenced in the license section (so sorry for that), all attributes should be a typical Ruby accessor, with the exception of the dependency method. (This also eliminates the need to initialize a default value, like @documentation, @license_text = {}, {})

I suggest the following:

s.documentation = { :appledoc => ['--project-name', '#{@name}',
                                                   '--project-company', '"Company Name"',
                                                   '--company-id', 'com.company',
                                                   '--output', './doc',
                                                   '--ignore', 'Common',
                                                   '--ignore', '.m'] }

(Note In case none of the arguments contains a space, you can also use the %w{} array literal.)

If I am not missing something I had to use s.license_text[:file] s.license_text[:range] s.license_text[:text]. If I convert s.license to a hash it would break the compatibility with all existing pods. I encouraged the link to license file that is directly maintained by the pod owned.

An example of what I meant would be:

class Specification
  def license=(name, options = {})
    @license = options.merge(:name => name)
  end
end

This makes all the examples I gave work, although you probably have to specify the Hash curly braces as well. E.g.

s.license = 'MIT', { :file => 'LICENSE', :range => 1..15 }

In addition, since only the first of the two parameters is required, this is backwards compatible with any existing podspec.

@fabiopelosin
Owner

Thanks for the explanation. I'm quite new to ruby and the minimalism of the syntax sometimes throws me off. Now everything is a default accessor.

Style

I have formated the sample to simplify the commenting and uncommenting of single keys on the hashes. I'm not sure if this is aligned with the style of the project.

            s.license  = {
              :type => 'MIT',
              :file => 'LICENSE',
            #  :range => 1..15,
            #  :text => 'Permission is hereby granted ...'
            }

License

As the license is now a hash it breaks the following tests. It should not be a problem if the license field was not used before.


Bacon::Error: {:type=>"MIT", :file=>"LICENSE"}.==("MIT") failed
Bacon::Error: {:type=>"MIT"}.==("MIT") failed

At the moment the setter is compatible with the following alternative syntaxes. I'm using the last one in the sample.

s.license = 'MIT'
s.license = 'MIT', { :file => 'LICENSE', :range => 1..15 }
s.license = {:type => 'MIT', :file => 'LICENSE', :range => 1..15 }

I could not use your setter because it looks like that ruby wraps the arguments in an array for the methods ending in =.

Appledoc

Ok, so would the idea be that we keep a list of sanctioned doc tools and if it's one of those then execute the tool directly (i.e. not in a shell) so that the options can't also inject commands?

Should we use something like IO.popen: or ::popen3?

@alloy
Owner

I'm currently on the road, so can't comment too much. In any case, I really appreciate your persistence! :)

Regarding which library to use for the command, I think Open3 is the only one that will work how we need it to (I.e. no subshell) on both Ruby 1.8.7 and Ruby 1.9.

@fabiopelosin
Owner

It's a nice way to learn some good ruby... btw thanks for basically tutoring me. I'm a bit ashamed that it took me 3 commits and all this wall of words for 2 accessors :-).

I added the first draft for installing the documentation. I added the method install_documentation to the localPod class. The call is made in ìnstallbut I'm thinking about moving it toinstall_dependencies!` so the documentation is installed only if the pod does not exits.

Finally I think that there should be an option in the pod file for specifying if pod install should install or just generate the documentation. Something like:

documentation :no # default
documentation :generate
documentation :install
@alloy
Owner

I have formated the sample to simplify the commenting and uncommenting of single keys on the hashes. I'm not sure if this is aligned with the style of the project.

Looks good.

As the license is now a hash it breaks the following tests.

Yeah those tests should just be updated, there's no actual code that does anything with the license field currently.

At the moment the setter is compatible with the following alternative syntaxes. I'm using the last one in the sample.

Now I’m wondering if we should not just deprecate the string-only variant (the old style), because otherwise we still can’t reliably aggregate the licenses. But that’s for after this patch.

I could not use your setter because it looks like that ruby wraps the arguments in an array for the methods ending in =.

That’s ok, I’ll see if can compact the code a bit more once it's in.

It's a nice way to learn some good ruby... btw thanks for basically tutoring me. I'm a bit ashamed that it took me 3 commits and all this wall of words for 2 accessors :-).

Hahaha. No worries, I think it’s great you’re doing your bit even if you aren’t familiar with the language :)

I added the first draft for installing the documentation. I added the method install_documentation to the localPod class. The call is made in ìnstallbut I'm thinking about moving it to install_dependencies!` so the documentation is installed only if the pod does not exits.

That sounds like an excellent plan.

Finally I think that there should be an option in the pod file for specifying if pod install should install or just generate the documentation.

Wether or not you want to install the docs is up to the developer. The Podfile is meant to be shared, so we can’t make such decisions there. These should just be command-line options, we can improve settings defaults later on (somewhere in ~/).

@fabiopelosin fabiopelosin referenced this issue from a commit
@fabiopelosin fabiopelosin [#149] Install or generate documentation
- introduced '--generate_documentation' '--install_documentation' command
  line options
- only doc installation/generation only if pod does not exists
a9d33c2
@fabiopelosin

Yeah those tests should just be updated

I have updated the tests. However I haven't introduced new ones to check if the documentation is being generated correctly. I'm waiting for the master branch to pass all the tests.

Wether or not you want to install the docs is up to the developer. The Podfile is meant to be shared, so we can’t make such decisions there. These should just be command-line options...

It makes a lot of sense, I introduced two command line arguments --install_documentation and --generate_documentation. They are a bit too long though.

@alloy
Owner

I have updated the tests. However I haven't introduced new ones to check if the documentation is being generated correctly. I'm waiting for the master branch to pass all the tests.

Ok, I’ll update the repo to work with the latest Xcodeproj version and then get rid of any failures.

It makes a lot of sense, I introduced two command line arguments --install_documentation and --generate_documentation. They are a bit too long though.

I’m thinking we can reverse it and do what rubygems does. So we generate and install docs by default, unless one of these options is used: --no-doc --no-doc-install. (Later on we can have a config file where the user can define her own global settings.)

In addition, I’m thinking about wether or not we should always try to generate/install docs if the appledoc tool is installed and no other documentation options where configured. But this is discussion for after this work has been merged.

@fabiopelosin

I’m thinking we can reverse it and do what rubygems does. So we generate and install docs by default, unless one of these options is used: --no-doc --no-doc-install.

I personally would prefer this approach because I always want to install the docs. I'll change it. For reference the rationale of the current implementation is:

  • for some users it could be unexpected that pod install would do something outside the scope of project folder, like overwriting an existing doc set.
  • appledoc uses an applescript for installing the docs and it causes Xcode to launch (if it isn't running).
@alloy
Owner

for some users it could be unexpected that pod install would do something outside the scope of project folder, like overwriting an existing doc set.

We’ll just see about that when and if we get any complaints about it, just doing it is the best way to find out :)

Ok I now have all the specs green locally, though I did once have to rm the VCR lib cache from spec/fixtures/vcr/tarballs.yml. Also don’t forget to do a git submodule update.

@alloy
Owner

(There are also still a few failures on Travis, but I have not yet been able to reproduce it locally.)

@fabiopelosin

I have an error that might be related to the ones seen in Travis

Errno::ENOENT: No such file or directory - /Users/fabio/Documents/GitHub/CocoaPods/tmp/Pods/JSONKit/CHANGELOG.md
    /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/pathname.rb:763:in `read': A full (integration spec) installation for platform `ios' - installs a library with a podspec defined inline
    /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/ruby/1.8/pathname.rb:763:in `read'
    ./spec/integration_spec.rb:126
    /Library/Ruby/Gems/1.8/gems/mocha-on-bacon-0.2.0/lib/mocha-on-bacon.rb:57:in `call'
    /Library/Ruby/Gems/1.8/gems/mocha-on-bacon-0.2.0/lib/mocha-on-bacon.rb:57:in `it'
    /Library/Ruby/Gems/1.8/gems/mocha-on-bacon-0.2.0/lib/mocha-on-bacon.rb:54:in `it'
    ./spec/integration_spec.rb:101
    ./spec/integration_spec.rb:31
    ./spec/integration_spec.rb:30:in `each'
    ./spec/integration_spec.rb:30

The strange thing is that CHANGELOG.md` exists and it is from v1.3 or later and not the expected (and tested) v1.2

@alloy
Owner

Woah, that's a weird one. Can you consistently reproduce it? If not, can you see if you still have the full log? Because if you use rake spec, it will shuffle the specs to test that there are no order dependencies, in which case we might be able to reproduce it by running the exact same command again.

@fabiopelosin

The error was resolved with

$ m -rf spec/fixtures/integration/JSONKit
$ git submodule update --init

I was consistently able to reproduce it and I'm not sure of what caused it. For reference here it is the full log.

By the way is expected that kicker fails?

$ kicker -c 

12:25:40.61 | Watching for changes on: /Users/fabio/Documents/GitHub/CocoaPods
12:25:40.61 | 
./.kick:3: uninitialized constant Ruby (NameError)
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/lib/kicker/recipes/dot_kick.rb:17:in `load'
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/lib/kicker/recipes/dot_kick.rb:17:in `load!'
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/lib/kicker/recipes/dot_kick.rb:45
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/lib/kicker/callback_chain.rb:9:in `call'
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/lib/kicker/callback_chain.rb:9:in `call'
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/lib/kicker/callback_chain.rb:7:in `each'
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/lib/kicker/callback_chain.rb:7:in `call'
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/lib/kicker.rb:77:in `run_startup_chain'
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/lib/kicker.rb:36:in `start'
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/lib/kicker.rb:16:in `run'
    from /Library/Ruby/Gems/1.8/gems/kicker-2.5.0/bin/kicker:10
    from /usr/bin/kicker:19:in `load'
    from /usr/bin/kicker:19
@alloy
Owner

I was consistently able to reproduce it and I'm not sure of what caused it.

Yeah working with git submodule is not as transparent as it should be imo.

By the way is expected that kicker fails?

Oops, I forgot to push the change needed for Kicker 2.5.0. I think bd53fda should be ok.

@fabiopelosin fabiopelosin referenced this issue from a commit
@fabiopelosin fabiopelosin [#149] Improved documentation generation
- refactoring
- default options for appledoc
- added command line arguments to pod install
- added option to force documentation generation with appledoc
98c972e
@fabiopelosin

Improvements

  • refactored code
  • added defaults for appledoc options
    • it is possible for a spec to support appledoc simply with s.documentaion = {:appledoc => []}
  • converted pod install command line options to --no-doc and --no-doc-install
  • added --doc-force that generates appledoc with default settings on all pods.

Notes

  • the documentation files are stored in Pods/Documentation/#{name}/
    • appledoc is called with --keep-intermediate-files to preserve the html when installing the documentation. I'm not sure if this is the correct approach.
  • --doc-force installs empty doc sets in Xcode if the pod doesn't have any appledoc comment (e.g. if they don't start with a double star). I don't know if would be appropriate fill the issue to appledoc to prevent the installation of empty docsets.
  • the code is commented. I can remove the comments if you prefer as the coding style of cocoa pods
  • there is support for multiple documentation strategies. The algo for atom links installation is outlined but it could be a little to hairy because it requires to parse the xml, download the file, and uncompress it if needed. I'm thinking about discarding all the atom stuff

Test

I have in ming the following test.

  • funcitonal: Pods/Documentation/#{name}/ is correctly created.
  • Xcode integration: the docset is correctly created in ~/Library/Developer/Shared/Documentation/DocSets/.

I don't plan to add test for all the options. @alloy what do you think. Could you kickstart me about where it would be more appropriate to create those tests?

@alloy
Owner

added --doc-force that generates appledoc with default settings on all pods

it is possible for a spec to support appledoc simply with s.documentaion = {:appledoc => []}

I was under the impression that you agreed with me that we should always generate docs with appledoc by default? That also removes the need for the second quote.

I'm thinking about discarding all the atom stuff

I agree. It makes the code simpler and you will always have docs up-to-date for the version you’re working with.

I don't plan to add test for all the options. @alloy what do you think.

Just to be clear, can you list the options that you mean?

Could you kickstart me about where it would be more appropriate to create those tests?

Sure thing! Does it matter to your planning if I do it now or tonight?

@fabiopelosin

I was under the impression that you agreed with me that we should always generate docs with appledoc by default? That also removes the need for the second quote.

I didn't plan to introduce it. I did because it was easy while introducing the appledoc defaults and I forgot the details of the previous discussion :-) Now I changed it to --no-doc-force. However I still have some remarks about the empty docsets

Just to be clear, can you list the options that you mean?

I meant testing pod install doc options (--no-doc, --no-doc-force, --no-doc-install) or testing only the defaults. Actually it was more a question about if you suggest to do it or not.

Sure thing! Does it matter to your planning if I do it now or tonight?

Thanks, no hurry at all.

Other Notes

Apple doc generates a copyright statement with the authors names for the current year at the bottom of the documentation. I don't know if it is a big deal. I tried to change it with appledoc --docset-copyright ... but it affects only the docset description in Xcode settings and not the generated html.

pod install --help alignment breaks because the new options are too long. Do you suggest to change the alignment everywhere?

    ...
    --no-clean  Leave SCM dirs like `.git' and `.svn' in tact after downloading
    --no-update Skip running `pod repo update` before install
    --no-doc    Skip documentation generation
    --no-doc-force Generate documentation only for the pods that support it
    --no-doc-install Skip documentation installation to Xcode
    --help      Show help information
    --silent    Print nothing
    --verbose   Print more information while working
    --version   Prints the version of CocoaPods
@fabiopelosin

Oh, I was forgetting. The default option that I set for appledocs inserts the version of the pod in the documentation name like Facebook-iOS-SDK (1.2) this allows to multiple version of the documentation to coexist. What do you think about it?

Moreover, after some more testing I see that processing pods with appledocs by default is a really nice solution and works very well for ones of my projects... with no need to change any podspec. I plan to change the default podspec description to include the defaults and specify to change them only if customization is needed.

@alloy
Owner

Tests

I meant testing pod install doc options (--no-doc, --no-doc-force, --no-doc-install) or testing only the defaults. Actually it was more a question about if you suggest to do it or not.

I don’t think there have to be any specific tests for these options, because they probably have to be used to disable doc gen in many other tests. If disabling would fail, we'd notice that soon enough by the tests taking much longer to run.

It would be nice, however, to add a test to the integration spec that goes through the full stack. Something like:

  it "generates documentation of all pods by default" do
    podfile = Pod::Podfile.new do
      self.platform :ios
      dependency 'JSONKit', '1.3'
      dependency 'SSToolkit'
    end

    installer = SpecHelper::Installer.new(podfile)
    installer.install!

    doc = (config.project_pods_root + 'Documentation/JSONKit/index.atom').read
    doc.should.include?('<title>JSONKit (1.3)</title>')

    doc = (config.project_pods_root + 'Documentation/SSToolkit/index.atom').read
    doc.should.include?('<title>SSToolkit (0.1.3)</title>')
  end

This only needs to run once, so add it somewhere inside the hideous ‘run once’ hack :)

In addition it would be nice if you could add a test that verifies that the options are being used. Maybe change the title or something.

Xcode integration: the docset is correctly created in ~/Library/Developer/Shared/Documentation/DocSets/.

Can you specify a different install destination somehow? Because during the test this should install into the temporary_directory, not the normal path.

Other Qs

However I still have some remarks about the empty dockets

Hmm, I lost track… :) Can you repeat what these remarks are?

Apple doc generates a copyright statement with the authors names for the current year at the bottom of the documentation. I don't know if it is a big deal. I tried to change it with appledoc --docset-copyright ... but it affects only the docset description in Xcode settings and not the generated html.

I’m not sure about all the details regarding appledoc, I have never used it myself yet. If that’s the only option to specify these details then let's at least do that.

pod install --help alignment breaks because the new options are too long. Do you suggest to change the alignment everywhere?

Yes please.

Oh, I was forgetting. The default option that I set for appledocs inserts the version of the pod in the documentation name like Facebook-iOS-SDK (1.2) this allows to multiple version of the documentation to coexist. What do you think about it?

Looks great.

Moreover, after some more testing I see that processing pods with appledocs by default is a really nice solution and works very well for ones of my projects... with no need to change any podspec. I plan to change the default podspec description to include the defaults and specify to change them only if customization is needed.

Awesome! I’m really looking forward to giving it a try :)

So, since it seems to work good, I don’t really see the need for --no-doc-force. Can we leave that out for now? Or was there a specific reason I’ve overlooked.

@fabiopelosin

Options

Hmm, I lost track… :) Can you repeat what these remarks are?

Lol... this is quite a long thread. The issue is that appledoc installs an empty docset if there is no valid documentation. The docset is listed in the "Organizer - Documentation" window of Xcode, but it does nothing when you click on it. See appledoc#204.

However playing with appledoc options I discovered that using --keep-undocumented-objects and --keep-undocumented-members could be a reasonable default. This solves the issue of the empty docsets at the cost of some empty methods/properties (img). However there is generally a readme file that is picked up and provides the documentation (img). Also, even if you don't have any description, at least you have a concise list of the methods/properties.

In this album you can also find an example of the atom documentation and one of the generated docset (the one with the version in the title) for BlocksKit.

So, since it seems to work good, I don’t really see the need for --no-doc-force. Can we leave that out for now? Or was there a specific reason I’ve overlooked.

I went a step ahead and removed also --no-doc-install option assuming that if you want the docs you want them installed. The functionality is still there for the tests. So now the only new option is no-doc.

Rakefile

I get an error in rake examples:build, is it expected?

I changed the path of the simulator to the new location in Xcode 4.3. And accidentally committed the file, I can remove it from the pull request if needed.

Conclusion

I think that the patch is finally done. All the test have been implemented and rake spec has not errors or failures. What do you think?

Btw thanks for the mention in twitter :-).

@alloy
Owner

I get an error in rake examples:build, is it expected?

I changed the path of the simulator to the new location in Xcode 4.3. And accidentally committed the file, I can remove it from the pull request if needed.

That should probably check if /Applications/Xcode.app exists and otherwise fallback, but I can do that after the merge, as my macbook I’m on does not have 4.3 yet.

Lol... this is quite a long thread. The issue is that appledoc installs an empty docset if there is no valid documentation. The docset is listed in the "Organizer - Documentation" window of Xcode, but it does nothing when you click on it. See appledoc#204.

Ok, gotcha :)

However playing with appledoc options I discovered that using --keep-undocumented-objects and --keep-undocumented-members could be a reasonable default. This solves the issue of the empty docsets at the cost of some empty methods/properties (img). However there is generally a readme file that is picked up and provides the documentation (img). Also, even if you don't have any description, at least you have a concise list of the methods/properties.

In this album you can also find an example of the atom documentation and one of the generated docset (the one with the version in the title) for BlocksKit.

Awesome, I think that looks great and will already be helpful.

I think that the patch is finally done. All the test have been implemented and rake spec has not errors or failures. What do you think?

Sweeet. Going to grab some coffee and pull it in to have a play!

Btw thanks for the mention in twitter :-).

Dude, you rock :)

@alloy
Owner

I went a step ahead and removed also --no-doc-install option assuming that if you want the docs you want them installed. The functionality is still there for the tests. So now the only new option is no-doc.

Good call!

@alloy
Owner

Merged it! :)

I did a bit more work and there are a couple of small other issues, but I will get at those tomorrow and then close this ticket.

Thanks! And you now have push access to this repo, so feel free to work on it more :)

@alloy
Owner

Ok, improved one more thing and created ticket #175 for another issue.

Please create new tickets for issues that I may have missed, it’s time to close this epic thread :)

Thanks again for all your work on this, it has imo greatly improved the UX.

@alloy alloy closed this
@fabiopelosin fabiopelosin referenced this issue from a commit
@fabiopelosin fabiopelosin [#149] Install or generate documentation
- introduced '--generate_documentation' '--install_documentation' command
  line options
- only doc installation/generation only if pod does not exists
0366b0a
@fabiopelosin fabiopelosin referenced this issue from a commit
@fabiopelosin fabiopelosin [#149] Improved documentation generation
- refactoring
- default options for appledoc
- added command line arguments to pod install
- added option to force documentation generation with appledoc
0036ad6
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.