Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 117 lines (68 sloc) 9.394 kb
5d5f58e @tomaz Added default readme file.
authored
1 About appledoc
2 ==============
3
4 appledoc is command line tool that helps Objective-C developers generate Apple-like source code documentation from specially formatted source code comments. It's designed to take as readable source code comments as possible for the input and use comments as well as surrounding source code to generate visually appealing documentation in the form of HTML as well as fully indexed and browsable Xcode documentation set. Although there are several tools that can create HTML documentation for Objective-C, all of those know to me fall short in meeting the minimum of goals described below.
5
6 Main goals of appledoc:
7
8 - Human-readable source code comments.
9 - Simple cross references to objects and members.
10 - Generate Apple-like source code HTML documentation.
11 - Generate and install fully indexed and browsable Xcode documentation set.
12 - Single tool to drive generation from source code parsing to documentation set installation.
13 - Easily customizable output.
14 - 100% Objective-C implementation for easy debugging.
15
e5e520e @tomaz Reorganized and updated readme file with troubleshooting information.…
authored
16 To make your experience with appledoc as smooth as possible, we warmly suggest reading this whole document as well as all online documentation mentioned in "using appledoc" section below!
5d5f58e @tomaz Added default readme file.
authored
17
1b9a0bd @tomaz IMPORTANT: Updated license to modified BSD license!
authored
18 Usage of appledoc is allowed under the terms listed in LICENSE section at the bottom of this file!
19
022d674 @tomaz Added twitter name to readme.
authored
20 Want to keep updated? Follow us on Twitter - [@gentlebytes](http://twitter.com/gentlebytes).
21
5d5f58e @tomaz Added default readme file.
authored
22
e5e520e @tomaz Reorganized and updated readme file with troubleshooting information.…
authored
23 Quick install
24 =============
25
26 The recommended way is to clone GitHub project and compile the tool from Xcode. As cloning GitHub project will create the link to the main repository, it greatly simplifies future upgrading too. To install, type the following in the Terminal:
5d5f58e @tomaz Added default readme file.
authored
27
28 git clone git://github.com/tomaz/appledoc.git
29
e5e520e @tomaz Reorganized and updated readme file with troubleshooting information.…
authored
30 This creates appledoc directory. Within you can find appledoc.xcodeproj Xcode project; open it and compile appledoc target - this should work out of the box, however your system must meet minimum system requirements, see below. I recommend you copy resulting appledoc executable from build directory to one of the directories in your path (`echo $PATH`) to make it easily accessible.
31
03adcda @Daij-Djan appledoc now embeds the default templates, installing them on demand …
Daij-Djan authored
32 Optional:
33 Appledoc is selfcontained and contains the necessary template files. IF you want to modify these default from Templates subdirectory to one of the expected locations:
5d5f58e @tomaz Added default readme file.
authored
34
35 - ~/Library/Application Support/appledoc
36 - ~/.appledoc
37
4b12f15 @SevInf Added instructions for installation script to readme
SevInf authored
38 You can also use install-appledoc.sh script to perform quick installation. Open Terminal and switch to appledoc directory. Type following command:
39
03adcda @Daij-Djan appledoc now embeds the default templates, installing them on demand …
Daij-Djan authored
40 sudo sh install-appledoc.sh (if you need templates add '-t default')
4b12f15 @SevInf Added instructions for installation script to readme
SevInf authored
41
03adcda @Daij-Djan appledoc now embeds the default templates, installing them on demand …
Daij-Djan authored
42 It compiles appledoc and installs its binary to /usr/local/bin and templates (if wanted) to ~/.appledoc by default. You can override this directories with -b and -t options respectively. For example:
4b12f15 @SevInf Added instructions for installation script to readme
SevInf authored
43
44 sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application\ Support/appledoc
0b7ba6a @cknadler Updates readme with homebrew installation info.
cknadler authored
45
46 **Alternatively with Homebrew:**
47
03adcda @Daij-Djan appledoc now embeds the default templates, installing them on demand …
Daij-Djan authored
48 brew install appledoc (homebrew currently installs templates by default)
0b7ba6a @cknadler Updates readme with homebrew installation info.
cknadler authored
49
83e2571 @lukaskubanek Fixed a typo
lukaskubanek authored
50 Homebrew puts your templates in `~/Library/Application Support/appledoc`.
db626c3 @tomaz Changed readme file to include preffered mail and cleaned up text.
authored
51
e5e520e @tomaz Reorganized and updated readme file with troubleshooting information.…
authored
52 Using appledoc
53 ==============
5d5f58e @tomaz Added default readme file.
authored
54
e08e80a @tomaz Updated read me for Google groups information.
authored
55 Use `appledoc --help` to see the list of all command line switches. Read more about appledoc on [appledoc site](http://gentlebytes.com/appledoc) - don't forget to check short help, documentation and tips while there!
56
57 Use [appledoc Google group](https://groups.google.com/forum/#!forum/appledoc) as a forum for questions on usage or other general questions.
58
59 Use [appledoc issues page](https://github.com/tomaz/appledoc/issues) to submit bug and feature requests. Before submitting new issues, check the forums to see if your question is answered there - unless you can confirm your issue as a new feature request or a bug, you should start at the forum to keep GitHub issues clean. Also read through issues to see if the issue is already there and vote on it or add a comment (don't forget about closed issues).
5d5f58e @tomaz Added default readme file.
authored
60
e5e520e @tomaz Reorganized and updated readme file with troubleshooting information.…
authored
61 Installation tips
62 -----------------
5d5f58e @tomaz Added default readme file.
authored
63
e5e520e @tomaz Reorganized and updated readme file with troubleshooting information.…
authored
64 To keep up to date, just go to Terminal and cd into appledoc directory, issue `git pull` and recompile appledoc.xcodeproj. Don't forget to overwrite appledoc executable you've copied to $PATH :)
5d5f58e @tomaz Added default readme file.
authored
65
e5e520e @tomaz Reorganized and updated readme file with troubleshooting information.…
authored
66 If you also want to compile and run AppledocTests (unit tests) target, you need to copy all the frameworks indicated within Libraries & Frameworks group to shared frameworks directory before building unit tests target! This is not required for building the appledoc tool itself.
67
68 Troubleshooting
69 ---------------
70
71 Have problems? This is what you can do to troubleshoot:
72
3f08d5c @tomaz Removed development branch description from the readme file.
authored
73 1. Make sure you have the latest appledoc version. Try `git pull` and run with latest version again.
03adcda @Daij-Djan appledoc now embeds the default templates, installing them on demand …
Daij-Djan authored
74 2. IF you have template files installed, make sure you're using the latest - delete the predefined folders and have appledoc copy the files from its embedded archive again (see Quick Install section above).
3f08d5c @tomaz Removed development branch description from the readme file.
authored
75 3. Increase verbosity level with `--verbose` command line switch. Default level is 2, but you can progressively increment verbosity up to 6 with each level giving you more detailed information. As this will give you a lot more information, you may want to concentrate only on specific set of source files you have problem with. Note that increasing verbosity will result in slower performance so using levels above 4 for every day use is not recommended.
76 4. Appledoc is open source project! You have all the source code available, so run it from Xcode. You can setup Xcode to pass the desired command line arguments and add breakpoints to help you isolate your issue. If you feel you'd like to contribute more to community, you are welcome to fork the project on GitHub and add features to it. Keep us posted so we can add these features to main repository as well - include unit tests if possible.
77 5. If you think you found a bug or want to request new feature, go to [appledoc issues page](https://github.com/tomaz/appledoc/issues). First read existing issues to see if there is already a request there (if you're using master branch, also read closed issues as your request may have already been covered but isn't yet merged on master branch). You can vote on existing requests to help us decide which features to concetrate on or you can add a comment to aid in solving it. If you don't find the request there, create a new issue; include parts of source files that give you problems if possible and/or description or steps that lead to it.
78 6. If you're having problems with some of your source files and don't want to publish them online, you can contact us through email below. We'll do our best to help you out, but bear in mind appledoc is not commercial product; it's created and maintaned in our spare time, so resources are limited.
79
e5e520e @tomaz Reorganized and updated readme file with troubleshooting information.…
authored
80
1b9a0bd @tomaz IMPORTANT: Updated license to modified BSD license!
authored
81 Developer notes
82 ---------------
83
84 If you wish to contribute, see Developer Notes file for short overview of how appledoc works internally.
85
86
e5e520e @tomaz Reorganized and updated readme file with troubleshooting information.…
authored
87 Minimum system requirements
88 ---------------------------
89
90 - Xcode 3.2 or greater for compiling
91 - OS X 10.6 for running
5d5f58e @tomaz Added default readme file.
authored
92
93
1b9a0bd @tomaz IMPORTANT: Updated license to modified BSD license!
authored
94 LICENSE
5d5f58e @tomaz Added default readme file.
authored
95 =======
96
1b9a0bd @tomaz IMPORTANT: Updated license to modified BSD license!
authored
97 appledoc is licensed with modified BSD license. In plain language: you're allowed to do whatever you wish with the code, modify, redistribute, embed in your products (free or commercial), but you must include copyright, terms of usage and disclaimer as stated in the license, the same way as any other BSD licensed code. You can of course use documentation generated by appledoc for your products (free or commercial), but you must attribute appledoc either in documentation itself or other appropriate place such as your website.
98
99 If for whatever reason you cannot agree to these terms, contact us through contact form on [our about page](http://gentlebytes.com/about), we'll do our best to help you out you out and find a workable solution!
100
101
f462686 @tomaz Updated licence format in readme to allow word wrapping.
authored
102 Copyright (c) 2009-2011, Gentle Bytes
103 All rights reserved.
1b9a0bd @tomaz IMPORTANT: Updated license to modified BSD license!
authored
104
f462686 @tomaz Updated licence format in readme to allow word wrapping.
authored
105 Redistribution and use in source, binary forms and generated documentation, with or without modification, are permitted provided that the following conditions are met:
1b9a0bd @tomaz IMPORTANT: Updated license to modified BSD license!
authored
106
f462686 @tomaz Updated licence format in readme to allow word wrapping.
authored
107 - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
5d5f58e @tomaz Added default readme file.
authored
108
f462686 @tomaz Updated licence format in readme to allow word wrapping.
authored
109 - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
5d5f58e @tomaz Added default readme file.
authored
110
f462686 @tomaz Updated licence format in readme to allow word wrapping.
authored
111 - Redistributions of documentation generated by appledoc must include attribution to appledoc, either in documentation itself or other appropriate media.
5d5f58e @tomaz Added default readme file.
authored
112
f462686 @tomaz Updated licence format in readme to allow word wrapping.
authored
113 - Neither the name of the appledoc, Gentle Bytes nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
5d5f58e @tomaz Added default readme file.
authored
114
f462686 @tomaz Updated licence format in readme to allow word wrapping.
authored
115 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
5d5f58e @tomaz Added default readme file.
authored
116
db626c3 @tomaz Changed readme file to include preffered mail and cleaned up text.
authored
117 Gentle Bytes appledoc@gentlebytes.com
Something went wrong with that request. Please try again.