Commit aa5a7fe4 authored by Fabio Pelosin's avatar Fabio Pelosin

Remove documentation generation

Related #1037
parent b2c96cf7
......@@ -4,6 +4,17 @@ To install or update CocoaPods see this [guide](http://docs.cocoapods.org/guides
## Master
###### Enhancements
* The documentation generation has been removed from CocoaPods as it graduated
in CocoaDocs. This decision was taken because CocoaDocs is a much better
solution which doesn't clutters the Xcode docsets while still allowing to
access the docsets with Xcode and with Dash. Moreover removing this feature
keeps the installer leaner and easier to develop. Private pods can use pre
install hook to generate the documentation. If there will be enough demand
this feature might be reintegrated as plugin (see
[#1037](https://github.com/CocoaPods/CocoaPods/issues/1037)).
## 0.19.1
[CocoaPods](https://github.com/CocoaPods/CocoaPods/compare/0.19.0...0.19.1)
[cocoapods-core](https://github.com/CocoaPods/Core/compare/0.19.0...0.19.1)
......
......@@ -55,7 +55,6 @@ module Pod
autoload :Acknowledgements, 'cocoapods/generator/acknowledgements'
autoload :BridgeSupport, 'cocoapods/generator/bridge_support'
autoload :CopyResourcesScript, 'cocoapods/generator/copy_resources_script'
autoload :Documentation, 'cocoapods/generator/documentation'
autoload :DummySource, 'cocoapods/generator/dummy_source'
autoload :Markdown, 'cocoapods/generator/acknowledgements/markdown'
autoload :Plist, 'cocoapods/generator/acknowledgements/plist'
......
......@@ -9,7 +9,6 @@ module Pod
def options
[
["--no-clean", "Leave SCM dirs like `.git' and `.svn' intact after downloading"],
["--no-doc", "Skip documentation generation with appledoc"],
["--no-integrate", "Skip integration of the Pods libraries in the Xcode project(s)"],
["--no-repo-update", "Skip running `pod repo update` before install"],
].concat(super)
......@@ -22,7 +21,6 @@ module Pod
def initialize(argv)
config.clean = argv.flag?('clean', config.clean)
config.generate_docs = argv.flag?('doc', config.generate_docs)
config.integrate_targets = argv.flag?('integrate', config.integrate_targets)
config.skip_repo_update = !argv.flag?('repo-update', !config.skip_repo_update)
super
......
......@@ -11,8 +11,7 @@ module Pod
#
# ---
# skip_repo_update: true
# generate_docs: false
# install_docs: false
# new_version_message: false
#
DEFAULTS = {
:verbose => false,
......@@ -21,8 +20,6 @@ module Pod
:aggressive_cache => false,
:clean => true,
:generate_docs => true,
:install_docs => true,
:integrate_targets => true,
:new_version_message => true,
}
......@@ -42,8 +39,8 @@ module Pod
attr_accessor :silent
alias_method :silent?, :silent
# @return [Bool] Whether the generated documentation should be installed to
# Xcode.
# @return [Bool] Whether a message should be printed when a new version of
# CocoaPods is available.
#
attr_accessor :new_version_message
alias_method :new_version_message?, :new_version_message
......@@ -57,18 +54,6 @@ module Pod
attr_accessor :clean
alias_method :clean?, :clean
# @return [Bool] Whether the documentation should be generated for the
# installed Pods.
#
attr_accessor :generate_docs
alias_method :generate_docs?, :generate_docs
# @return [Bool] Whether the generated documentation should be installed to
# Xcode.
#
attr_accessor :install_docs
alias_method :install_docs?, :install_docs
# @return [Bool] Whether CocoaPods should integrate a user target and build
# the workspace or just create the Pods project.
#
......
require 'escape'
require 'active_support/core_ext/array/conversions'
module Pod
module Generator
# Generates the documentation for a Pod with the appledoc tool.
#
class Documentation
extend Executable
executable :appledoc
attr_reader :sandbox
attr_reader :specification
attr_reader :path_list
def initialize(sandbox, specification, path_list)
@sandbox = sandbox
@specification = specification.root
@path_list = path_list
end
DOC_SETS_PATH = "~/Library/Developer/Shared/Documentation/DocSets"
# @return [Bool] Whether the documentation for the current Pod is already
# installed in the system.
#
def already_installed?
index = spec_appledoc_options.index('--company-id')
company_id = index ? spec_appledoc_options[index + 1] : docs_id
docset_path = DOC_SETS_PATH + "/#{company_id}.#{name.gsub(/ /,'-')}.docset"
Pathname.new(File.expand_path(docset_path)).exist?
end
# Generates and optionally installs the documentation for the current
# Pod.
#
# @param [Bool] install_docset
# Whether the documentation should also be installed in Xcode.
#
# @note As the documentation is once per Pod to speed up the
# installation process it is generate for all the specs
# (including those not currently used). For this reason it is
# important that the documentation is generated before cleaning a
# Pod installation.
#
# @todo Passing the files explicitly clutters output and chokes on very
# long list (AWSiOSSDK). It is possible to just pass the dir of
# the pod, however this would include other files like demo
# projects.
#
# @return [void]
#
def generate(install_docset)
if `which appledoc`.strip.empty?
UI.warn "[!] Skipping documentation generation because appledoc can't be found.", [], true
return
end
target_path.mkpath
Dir.chdir(pod_root) do
appledoc apple_doc_command_line_arguments(install_docset)
end
if $?.exitstatus != 0
UI.warn "[!] Appledoc encountered an error (exitstatus: #{$?.exitstatus}), an update might be available to solve the issue."
end
end
#-----------------------------------------------------------------------#
public
# !@group Docset information.
# @return [String] The name of the docset
#
def name
specification.name + ' ' + specification.version.to_s
end
# @return [String] The company of the docset.
#
# @todo Set to CocoaPods?
#
def company
if specification.authors
specification.authors.keys.sort.to_sentence
else
'no-company'
end
end
# @return [String] The copyright of the docset.
#
def copyright
company
end
# @return [String] The description of the docset.
#
def description
specification.summary || specification.description || 'Generated by CocoaPods.'
end
# @return [String] The id of the docset, uniq for every Pod.
#
def docs_id
"org.cocoapods.#{specification.name.downcase}"
end
#-----------------------------------------------------------------------#
public
# !@group Paths.
# @return [Array<String>] the list of the headers to process
# with the appledoc tool.
#
def public_headers
absolute_paths = file_accessors.map(&:public_headers).flatten.uniq
absolute_paths.map { |f| f.relative_path_from(pod_root).to_s }
end
# @return [String] the path of the file to use as the index of
# documentation relative to the root of the Pod.
#
def index_file
readme_file = file_accessors.first.readme
readme_file.relative_path_from(pod_root).to_s if readme_file
end
#-----------------------------------------------------------------------#
public
# !@group Appledoc options.
# @return [Array<String>] The list of the appledoc options followed by
# their values as defined in the specification.
#
def spec_appledoc_options
return [] unless specification.documentation
specification.documentation[:appledoc] || []
end
# @return [Array<String>] The list of the appledoc options followed by
# their values.
#
# @note The appledoc tool terminates with an exits status of 1 if a
# warning was logged (see `--exit-threshold` option).
#
def appledoc_options
options = [
'--project-name', name,
'--docset-desc', description,
'--project-company', company,
'--docset-copyright', copyright,
'--company-id', docs_id,
'--ignore', '.m',
'--keep-undocumented-objects',
'--keep-undocumented-members',
'--keep-intermediate-files',
'--exit-threshold', '2'
]
options += ['--index-desc', index_file] if index_file
options += spec_appledoc_options
end
# @return [String] the arguments to pass to the appledoc command line
# tool, properly escaped.
#
# @param [Bool] install_docset
# Whether the documentation should also be installed in Xcode.
#
def apple_doc_command_line_arguments(install_docset)
arguments = appledoc_options
arguments += ['--output', target_path.to_s]
arguments += install_docset ? ['--create-docset'] : ['--no-create-docset']
arguments += public_headers
Escape.shell_command(arguments)
end
#-----------------------------------------------------------------------#
private
# !@group Private Helpers
def target_path
sandbox.documentation_dir + specification.name
end
def pod_root
path_list.root
end
def file_accessors
return @file_accessors if @file_accessors
@file_accessors = []
all_specs = [specification, *specification.subspecs]
all_specs.each do |spec|
spec.available_platforms.each do |platform|
accessor = Sandbox::FileAccessor.new(path_list, spec.consumer(platform))
@file_accessors << accessor
end
end
@file_accessors
end
end
end
end
......@@ -254,8 +254,6 @@ module Pod
@pod_installers ||= []
pod_installer = PodSourceInstaller.new(sandbox, specs_by_platform)
pod_installer.aggressive_cache = config.aggressive_cache?
pod_installer.generate_docs = config.generate_docs?
pod_installer.install_docs = config.install_docs?
pod_installer.install!
@pod_installers << pod_installer
@installed_specs.concat(specs_by_platform.values.flatten.uniq)
......
......@@ -24,8 +24,6 @@ module Pod
@sandbox = sandbox
@specs_by_platform = specs_by_platform
@generate_docs = false
@install_docs = false
@aggressive_cache = false
end
......@@ -41,18 +39,6 @@ module Pod
# @!group Configuration
# @return [Bool] whether the documentation should be generated for the
# Pod.
#
attr_accessor :generate_docs
alias_method :generate_docs?, :generate_docs
# @return [Bool] whether the generated documentation should be installed
# in Xcode.
#
attr_accessor :install_docs
alias_method :install_docs?, :install_docs
# @return [Bool] whether the downloader should always check against the
# remote if issues might be generated (mostly useful to speed up
# testing).
......@@ -73,8 +59,7 @@ module Pod
# @return [void]
#
def install!
download_source unless predownloaded? || local?
generate_docs if generate_docs?
download_source unless predownloaded? || local?
end
# Cleans the installations if appropriate.
......@@ -121,20 +106,6 @@ module Pod
end
end
# Generates the documentation for the Pod.
#
# @return [void]
#
def generate_docs
if documentation_generator.already_installed?
UI.section " > Using existing documentation"
else
UI.section " > Installing documentation" do
documentation_generator.generate(install_docs?)
end
end
end
# Removes all the files not needed for the installation according to the
# specs by platform.
#
......@@ -162,13 +133,6 @@ module Pod
@downloader
end
# @return [Generator::Documentation] The documentation generator to use
# for generating the documentation.
#
def documentation_generator
@documentation_generator ||= Generator::Documentation.new(sandbox, root_spec, path_list)
end
#-----------------------------------------------------------------------#
private
......
......@@ -191,7 +191,6 @@ module Pod
config.sandbox_root = validation_dir + 'Pods'
config.silent = !config.verbose
config.integrate_targets = false
config.generate_docs = false
config.skip_repo_update = true
end
......
......@@ -306,59 +306,53 @@ describe "Integration take 2" do
# Test subspecs inheritance
describe "Integrates a project with CocoaPods" do
check "install --no-repo-update --no-doc", "install_new"
check "install --no-repo-update", "install_new"
end
describe "Adds a Pod to an existing installation" do
check "install --no-repo-update --no-doc", "install_add_pod"
check "install --no-repo-update", "install_add_pod"
end
describe "Removes a Pod from an existing installation" do
check "install --no-repo-update --no-doc", "install_remove_pod"
check "install --no-repo-update", "install_remove_pod"
end
describe "Creates an installation with multiple target definitions" do
check "install --no-repo-update --no-doc", "install_multiple_targets"
check "install --no-repo-update", "install_multiple_targets"
end
describe "Installs a Pod with different subspecs activated across different targets" do
check "install --no-repo-update --no-doc", "install_subspecs"
check "install --no-repo-update", "install_subspecs"
end
describe "Installs a Pod with a local source" do
check "install --no-repo-update --no-doc", "install_local_source"
check "install --no-repo-update", "install_local_source"
end
describe "Installs a Pod with an external source" do
check "install --no-repo-update --no-doc", "install_external_source"
check "install --no-repo-update", "install_external_source"
end
describe "Installs a Pod given the podspec" do
check "install --no-repo-update --no-doc", "install_podspec"
check "install --no-repo-update", "install_podspec"
end
describe "Performs an installation using a custom workspace" do
check "install --no-repo-update --no-doc", "install_custom_workspace"
check "install --no-repo-update", "install_custom_workspace"
end
# @todo add tests for all the hooks API
#
describe "Runs the Podfile callbacks" do
check "install --no-repo-update --no-doc", "install_podfile_callbacks"
check "install --no-repo-update", "install_podfile_callbacks"
end
# @todo add tests for all the hooks API
#
describe "Runs the specification callbacks" do
check "install --no-repo-update --no-doc", "install_spec_callbacks"
check "install --no-repo-update", "install_spec_callbacks"
end
# @todo requires CocoaPods 0.17
#
# describe "Generates the documentation of Pod during installation" do
# check "install --no-repo-update --no-doc", "install_docs"
# end
end
#--------------------------------------#
......@@ -366,7 +360,7 @@ describe "Integration take 2" do
describe "Pod update" do
describe "Updates an existing installation" do
check "update --no-repo-update --no-doc", "update"
check "update --no-repo-update", "update"
end
end
......
......@@ -87,31 +87,5 @@ module Pod
#--------------------------------------#
if `which appledoc`.strip.empty?
puts " ! ".red << "Skipping because the `appledoc` executable can't be found."
else
# @todo fix the config of the hook
it "generates documentation of all pods by default" do
podfile = Podfile.new do
platform :ios
xcodeproj 'dummy'
pod 'JSONKit', '1.4'
pod 'SSToolkit', '1.0.0'
end
config.generate_docs = true
config.install_docs = false
Generator::Documentation.any_instance.stubs(:already_installed?).returns(false)
installer = Installer.new(config.sandbox, podfile)
installer.install!
doc = (config.sandbox_root + 'Documentation/JSONKit/html/index.html').read
doc.should.include?('<title>JSONKit 1.4 Reference</title>')
doc = (config.sandbox_root + 'Documentation/SSToolkit/html/index.html').read
doc.should.include?('<title>SSToolkit 1.0.0 Reference</title>')
end
end
end
end
......@@ -11,8 +11,6 @@ module Bacon
c.silent = true
c.repos_dir = fixture('spec-repos')
c.installation_root = SpecHelper.temporary_directory
c.install_docs = false
c.generate_docs = false
c.skip_repo_update = true
end
......
require File.expand_path('../../../spec_helper', __FILE__)
module Pod
describe Generator::Documentation do
before do
sandbox = config.sandbox
spec = fixture_spec('banana-lib/BananaLib.podspec')
root = fixture('banana-lib')
path_list = Sandbox::PathList.new(root)
@doc_installer = Generator::Documentation.new(sandbox, spec, path_list)
end
it 'returns the Pod documentation header files' do
@doc_installer.public_headers.sort.should == %w[ Classes/Banana.h ].sort
end
it 'returns an empty array in case there are no appledoc options specified' do
@doc_installer.specification.stubs(:documentation).returns({})
@doc_installer.spec_appledoc_options.should == []
end
it 'returns the Pod documentation options' do
expected = [
'--project-name', 'BananaLib 1.0',
'--docset-desc', 'Chunky bananas!',
'--project-company', 'Banana Corp and Monkey Boy',
'--docset-copyright', 'Banana Corp and Monkey Boy',
'--company-id', 'org.cocoapods.bananalib',
'--ignore', '.m',
'--keep-undocumented-objects',
'--keep-undocumented-members',
'--keep-intermediate-files',
'--exit-threshold', '2',
'--index-desc', 'README',
'--project-company', 'Banana Corp',
'--company-id', 'com.banana'
]
options = @doc_installer.appledoc_options
expected.each do |expected_option|
options.should.include?(expected_option)
end
end
it "returns the command line arguments to pass to the appledoc tool" do
arguments = @doc_installer.apple_doc_command_line_arguments(install_docset=false)
arguments.should.include?("--project-name 'BananaLib 1.0' ")
arguments.should.include?(" --docset-desc 'Chunky bananas!' ")
arguments.should.include?(" --project-company 'Banana Corp and Monkey Boy' ")
arguments.should.include?(" --docset-copyright 'Banana Corp and Monkey Boy' ")
arguments.should.include?(" --company-id org.cocoapods.bananalib ")
arguments.should.include?(" --ignore .m ")
arguments.should.include?(" --keep-undocumented-objects ")
arguments.should.include?(" --keep-undocumented-members ")
arguments.should.include?(" --keep-intermediate-files ")
arguments.should.include?(" --exit-threshold 2 ")
arguments.should.include?(" --index-desc README ")
arguments.should.include?(" --project-company 'Banana Corp' ")
arguments.should.include?(" --company-id com.banana ")
# arguments.should.include?(" --output tmp/Pods/Documentation/BananaLib ")
arguments.should.include?(" --no-create-docset Classes/Banana.h")
arguments.should.include?(" Classes/Banana.h")
end
#-------------------------------------------------------------------------#
if !`which appledoc`.strip.empty?
describe "Appledoc integration" do
before do
@doc_installer.generate(false)
end
it 'creates the html' do
docs_path = config.sandbox.root + "Documentation/BananaLib/html"
docs_path.should.exist
(docs_path + 'index.html').read.should.include?('BananaObj')
(docs_path + 'Classes/BananaObj.html').read.should.include?('Bananas are cool')
end
end
else
puts "[!] Skipping documentation generation specs, because appledoc can't be found."
end
end
end
......@@ -14,14 +14,6 @@ module Pod
describe "In General" do
it "doesn't generate docs by default" do
@installer.should.not.generate_docs?
end
it "doesn't installs the docs by default" do
@installer.should.not.install_docs?
end
it "doesn't use an aggressive cache by default" do
@installer.should.not.aggressive_cache?
end
......@@ -73,31 +65,6 @@ module Pod
#--------------------------------------#
describe "Documentation" do
it "generates the documentation if needed" do
@installer.generate_docs = true
@installer.documentation_generator.expects(:generate)
@installer.install!
end
it "doesn't generates the documentation if it is already installed" do
@installer.generate_docs = true
@installer.documentation_generator.stubs(:already_installed?).returns(true)
@installer.documentation_generator.expects(:generate).never
@installer.install!
end
it "doesn't generates the documentation if disabled in the config" do
@installer.generate_docs = false
@installer.documentation_generator.expects(:generate).never
@installer.install!
end
end
#--------------------------------------#
describe "Cleaning" do
it "cleans the paths non used by the installation" do
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment