Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Initial support for Specification DSL documentation.

  • Loading branch information...
commit c7545e8219d5e795529b06fa387d8ffe76bbfacd 1 parent f2a8503
@fabiopelosin fabiopelosin authored
Showing with 425 additions and 1 deletion.
  1. +1 −1  .gitignore
  2. +1 −0  .yardopts
  3. +95 −0 Rakefile
  4. +328 −0 doc/specification.md
View
2  .gitignore
@@ -20,5 +20,5 @@ spec/fixtures/mercurial-repo/.hg/*cache
.hg
spec/fixtures/vcr
.yardoc
-/doc
+/documentation
.rbx/
View
1  .yardopts
@@ -1,2 +1,3 @@
+--output-dir documentation
--markup markdown
--private
View
95 Rakefile
@@ -167,6 +167,101 @@ task :bootstrap do
`bundle install`
end
+# Generates markdown files for the documentation of the DSLs.
+#
+# Currently only the Specification DSL is supported.
+#
+# This task uses the comments and the attributes for genenarting the markdown.
+#
+desc "Genereates the documentation"
+task :doc do
+ ROOT = Pathname.new(File.expand_path('../../', __FILE__))
+ $:.unshift((ROOT + 'lib').to_s)
+ require 'cocoapods-core'
+ attributes = Pod::Specification.attributes
+
+ require 'yard'
+ YARD::Registry.load(['lib/cocoapods-core/specification/specification_dsl.rb'], true)
+
+ markdown = []
+ attributes = Pod::Specification.attributes
+ root_spec_attributes = attributes.select { |a| a.root_only }
+ subspec_attributes = attributes - root_spec_attributes
+
+ attributes.each do |attrb|
+ yard_object = YARD::Registry.at("Pod::Specification##{attrb.writer_name}")
+ if yard_object
+ puts "#{attrb.name} - #{yard_object.group}"
+ end
+ end
+
+ attributes_by_type = {
+ "Root specification attributes" => root_spec_attributes,
+ "Regular attributes" => subspec_attributes,
+ }
+
+ markdown << "\n# Podspec attributes"
+
+ # Overview
+ markdown << "\n## Overview"
+ attributes_by_type.each do |type, attributes|
+ markdown << "\n#### #{type}"
+ markdown << "<table><tr>"
+ attributes.each_with_index do |attrb, idx|
+ markdown << " <td>#{attrb.name}</td>"
+ markdown << "</tr>\n<tr>" if (idx + 1)% 3 == 0
+ end
+ markdown << "</table></tr>"
+ end
+
+ # Attributes details
+ attributes_by_type.each do |type, attributes|
+ markdown << "\n## #{type}"
+ attributes.each do |attrb|
+ yard_object = YARD::Registry.at("Pod::Specification##{attrb.writer_name}")
+ if yard_object
+ description = yard_object.docstring
+ examples = yard_object.docstring.tags(:example)
+ markdown << "#### #{attrb.name.to_s.gsub('_', '\_')}"
+ desc = attrb.required ? "[Required] " : " "
+ markdown << desc + "#{description}\n"
+
+ markdown << "This attribute supports multi-platform values.\n" if attrb.multi_platform
+ if attrb.keys.is_a?(Array)
+ markdown << "This attribute supports the following keys: `#{attrb.keys * '`, `'}`.\n"
+ elsif attrb.keys.is_a?(Hash)
+ string = "This attribute supports the following keys: "
+ attrb.keys.each do |key, subkeys|
+ string << "\n- `#{key}`"
+ string << ": `#{subkeys * '`, `'}`\n" if subkeys
+ end
+ markdown << string
+ end
+
+ # markdown << "###### Default Value\n"
+
+ markdown << "###### Examples\n"
+ examples.each do |example|
+ markdown << "```"
+ indent = "\n" << " " * (attrb.writer_name.length + 4)
+ example_text = example.text.gsub("\n", indent)
+ writer_name = attrb.writer_name.to_s.gsub('=', ' =')
+ on_platform = ''
+ on_platform = 'ios.' if example.name.include?('iOS')
+ on_platform = 'osx.' if example.name.include?('OS X')
+ markdown << "s.#{on_platform}#{writer_name} #{example_text}"
+ markdown << "```\n"
+ end
+ else
+ puts "Unable to find documentation for `Pod::Specification##{attrb.writer_name}`"
+ end
+ end
+ end
+
+ doc = markdown * "\n"
+ File.open('doc/specification.md', 'w') {|f| f.write(doc) }
+end
+
desc "Run all specs"
task :spec => 'spec:all'
View
328 doc/specification.md
@@ -0,0 +1,328 @@
+
+# Podspec attributes
+
+## Overview
+
+#### Root specification attributes
+<table><tr>
+ <td>name</td>
+ <td>version</td>
+ <td>authors</td>
+</tr>
+<tr>
+ <td>license</td>
+ <td>homepage</td>
+ <td>source</td>
+</tr>
+<tr>
+ <td>summary</td>
+ <td>description</td>
+ <td>documentation</td>
+</tr>
+<tr>
+</table></tr>
+
+#### Regular attributes
+<table><tr>
+ <td>platform</td>
+ <td>deployment_target</td>
+ <td>frameworks</td>
+</tr>
+<tr>
+ <td>weak_frameworks</td>
+ <td>libraries</td>
+ <td>source_files</td>
+</tr>
+<tr>
+ <td>exclude_source_files</td>
+ <td>public_header_files</td>
+ <td>resources</td>
+</tr>
+<tr>
+ <td>preserve_paths</td>
+ <td>exclude_header_search_paths</td>
+ <td>subspec</td>
+</tr>
+<tr>
+ <td>preferred_dependency</td>
+ <td>dependency</td>
+</table></tr>
+
+## Root specification attributes
+#### name
+[Required] The name of the Pod.
+
+###### Examples
+
+```
+s.name = 'MyPod'
+```
+
+#### version
+[Required] The version of the Pod (see [Semver](http://semver.org)).
+
+###### Examples
+
+```
+s.version = '0.0.1'
+```
+
+#### authors
+[Required] The email and the name of the authors of the library.
+
+###### Examples
+
+```
+s.authors = 'Darth Vader'
+```
+
+```
+s.authors = 'Darth Vader', 'Wookiee'
+```
+
+```
+s.authors = { 'Darth Vader' => 'darthvader@darkside.com',
+ 'Wookiee' => 'wookiee@aggrrttaaggrrt.com' }
+```
+
+#### license
+[Required] The license of the Pod, unless the source contains a file named
+`LICENSE.*` or `LICENCE.*` the path of the file containing the license
+or the text of the license should be specified.
+
+This attribute supports the following keys: `type`, `file`, `text`.
+
+###### Examples
+
+```
+s.license = 'MIT'
+```
+
+```
+s.license = { :type => 'MIT', :file => 'MIT-LICENSE.txt' }
+```
+
+```
+s.license = { :type => 'MIT', :text => <<-LICENSE
+ Copyright 2012
+ Permission is granted to...
+ LICENSE
+ }
+```
+
+#### homepage
+[Required] The URL of the homepage of the Pod.
+
+###### Examples
+
+```
+s.homepage = 'www.example.com'
+```
+
+#### source
+[Required] The location from where the library should be retrieved.
+
+This attribute supports the following keys:
+- `git`: `tag`, `branch`, `commit`, `submodules`
+
+- `svn`: `folder`, `tag`, `revision`
+
+- `hg`: `revision`
+
+- `http`
+###### Examples
+
+```
+s.source = :git => www.example.com/repo.git
+```
+
+```
+s.source = :git => www.example.com/repo.git, :tag => 'v0.0.1'
+```
+
+```
+s.source = :git => www.example.com/repo.git, :tag => "v#{s.version}"
+```
+
+#### summary
+[Required] A short description (max 140 characters).
+
+###### Examples
+
+```
+s.summary = 'A library that computes the meaning of life.'
+```
+
+#### description
+ An optional longer description that can be used in place of the summary.
+
+###### Examples
+
+```
+s.description = <<-DESC
+ A library that computes the meaning of life. Features:
+ 1. Is self aware
+ ...
+ 42. Likes candies.
+ DESC
+```
+
+#### documentation
+ Any additional option to pass to the
+[appledoc](http://gentlebytes.com/appledoc/) tool.
+
+###### Examples
+
+```
+s.documentation = :appledoc => ['--no-repeat-first-par',
+ '--no-warn-invalid-crossref']
+```
+
+
+## Regular attributes
+#### platform
+ The platform where this specification is supported.
+
+###### Examples
+
+```
+s.platform = :ios
+```
+
+```
+s.platform = :osx
+```
+
+```
+s.platform = :osx, "10.8"
+```
+
+#### deployment\_target
+ The deployment targets for the platforms of the specification.
+
+This attribute supports multi-platform values.
+
+###### Examples
+
+```
+s.ios.deployment_target = "6.0"
+```
+
+```
+s.osx.deployment_target = "10.8"
+```
+
+#### source\_files
+ The source files of the specification.
+
+This attribute supports multi-platform values.
+
+###### Examples
+
+```
+s.source_files = "Classes/**/*.{h,m}"
+```
+
+```
+s.source_files = "Classes/**/*.{h,m}", "More_Classes/**/*.{h,m}"
+```
+
+#### exclude\_source\_files
+ A pattern of files that should be excluded from the source files.
+
+This attribute supports multi-platform values.
+
+###### Examples
+
+```
+s.ios.exclude_source_files = "Classes/osx"
+```
+
+```
+s.exclude_source_files = "Classes/**/unused.{h,m}"
+```
+
+#### public\_header\_files
+ A pattern of files that should be used as public headers.
+
+This attribute supports multi-platform values.
+
+###### Examples
+
+```
+s.public_header_files = "Resources/*.png"
+```
+
+#### resources
+ A list of resources. These are copied into the target bundle with a
+build phase script.
+
+This attribute supports multi-platform values.
+
+###### Examples
+
+```
+s.resources = "Resources/*.png"
+```
+
+#### preserve\_paths
+ Any file that should not be cleaned (CocoaPods cleans all the unused
+files by default).
+
+This attribute supports multi-platform values.
+
+###### Examples
+
+```
+s.preserve_paths = "IMPORTANT.txt"
+```
+
+#### subspec
+ Specification for a module of the Pod. A specification automaically
+iherits as a dependency all it children subspecs.
+
+Subspec also inherits values from their parents so common values for
+attributes can be specified in the ancestors.
+
+This attribute supports multi-platform values.
+
+###### Examples
+
+```
+s.subspec
+ subspec "core" do |sp|
+ sp.source_files = "Classes/Core"
+ end
+
+ subspec "optional" do |sp|
+ sp.source_files = "Classes/BloatedClassesThatNobodyUses"
+ end
+```
+
+```
+s.subspec
+ subspec "Subspec" do |sp|
+ sp.subspec "resources" do |ssp|
+ end
+ end
+```
+
+#### preferred\_dependency
+ The name of the subspec that should be used as preferred dependency.
+This is useful in case there are incompatible subspecs or a subspec
+provides components that are rarely used.
+
+This attribute supports multi-platform values.
+
+###### Examples
+
+```
+s.preferred_dependency = 'Pod/default_subspec'
+```
+
+#### dependency
+
+
+This attribute supports multi-platform values.
+
+###### Examples
Please sign in to comment.
Something went wrong with that request. Please try again.