Skip to content
Browse files

Merge pull request #2 from samdeane/master

Tweaks...
  • Loading branch information...
2 parents 7b09d17 + b00a1bd commit 1ae0f2cb7f2a212f4925d5d3f3a94aef62aa3e3a @danielctull committed Nov 1, 2012
Showing with 42 additions and 20 deletions.
  1. +40 −0 README.md
  2. +2 −20 gendoc.sh
View
40 README.md
@@ -0,0 +1,40 @@
+Run the gendoc script from the root of your project.
+
+It makes a temporary directory and generates appledoc documentation for your project in that directory.
+
+It then makes a local clone of your documentation branch (called gh-pages, by default), copies the generated appledoc html into a folder in the branch (called Documentation by default), commits the new documentation and pushes it back to the project repo.
+
+At the same time, the script generates an Xcode docset for the documentation, installs it into the right place on your local machine, and includes it in the pages that get uploaded to github, along with an rss feed that can be used to subscribe to the docset.
+
+It then optionally pushes the new documentation back up to github (see Options below).
+
+## Assumptions
+
+This script assumes:
+- the name of the root folder is the name of the project
+- your appledoc templates are in ~/.appledoc (can be a symlink)
+- you have a GlobalSettings.plist file in your appledoc templates folder
+- you've set values in GlobalSettings.plist for --project-company, --company-id
+
+The script looks at the remotes configured in the repo to try to work out what your github
+user name is, so that it can generate the correct urls for a docset feed.
+It looks for the first remote with the pattern: git@github.com:yourname/
+
+## Options
+
+The script looks for a file `.appledoc.plist` at the root of your project. If it finds it, it reads additional appledoc settings from it. You can use this to customise your Appledoc settings on a per-project basis.
+
+There are also currently three options that you can set by editing the top of the script.
+
+Setting `publish` to true causes the generated pages to be pushed back up to github. If it's set to false, the script just echoes out the git command that you would need to use to do the push.
+
+Setting `open` to true opens the index page of the generated documentation in your default browser. Github can take a while to update the pages after you've pushed, so this isn't always a useful thing to do.
+
+Setting `editcommit` to true gives you a chance to edit the message used when committing the generated documentation to the gh-pages branch. I default this to false as these messages tend not to be particularly useful. Typically I will have used a sensible commit message when actually changing the source files from which the documentation is generated, so another commit message just to say that it's been generated tends to be overkill.
+
+One day I might get round to refining the script so that these options can be specified on the command line... one day...
+
+## Credits
+
+From an original script by Daniel Tull.
+Somewhat mangled by Sam Deane.
View
22 gendoc.sh 100644 → 100755
@@ -3,25 +3,7 @@
# From an original script by Daniel Tull
# Somewhat mangled by Sam Deane
-# Run this script from the root of your project.
-# It makes a temporary directory and generates appledoc documentation for your
-# project in that directory.
-# It then makes a local clone of your documentation branch (called gh-pages, by default)
-# copies the generated appledoc html into a folder in the branch (called Documentation by default)
-# commits the new documentation and pushes it back to the project repo.
-#
-# Note that it doesn't push from the project repo, so the new documentation doesn't leave
-# your machine - but it echos the git command that you'll need to execute to do the push.
-
-# This script assumes:
-# - the name of the root folder is the name of the project
-# - your appledoc templates are in ~/.appledoc (can be a symlink)
-# - you have a GlobalSettings.plist file in your appledoc templates folder
-# - you've set values in GlobalSettings.plist for --project-company, --company-id
-
-# The script looks at the remotes configured in the repo to try to work out what your github
-# user name is, so that it can generate the correct urls for a docset feed.
-# It looks for the first remote with the pattern: git@github.com:yourname/
+# See README.md for an explanation of what this script does and how to use it.
git=`xcrun --find git`
docsetutil=`xcrun --find docsetutil`
@@ -89,7 +71,7 @@ appledoc \
--docset-atom-filename "docset.atom" \
--docset-feed-url "http://$githubuser.github.com/$projectname/$docdirectory/%DOCSETATOMFILENAME" \
--docset-package-url "http://$githubuser.github.com/$projectname/$docdirectory/%DOCSETPACKAGEFILENAME" \
- --docset-fallback-url "http://$githubuser.github.com/projectname/$docdirectory/" \
+ --docset-fallback-url "http://$githubuser.github.com/$projectname/$docdirectory/" \
--project-name $projectname \
-o "$tempdir" "$@" $settings ./

0 comments on commit 1ae0f2c

Please sign in to comment.
Something went wrong with that request. Please try again.