Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Per-project Settings #67

Closed
davedelong opened this Issue · 8 comments

3 participants

Dave DeLong tomaz Carter Allen
Dave DeLong

Doxygen allows you to create a "Doxyfile" inside a project directory that contains settings overrides for Doxygen when run on that directory. There doesn't appear to be anything like this for AppleDoc. Perhaps there could be support for an "appledoc.plist" file with local, project-specific settings?

tomaz
Owner

My idea was to have all options through command line and have it run as Xcode build script. So in a way the build script would be your "project settings". From the start I was designing it to have as simple command line as possible and I implemented this through sesible defaults and global settings.

As of now, there is no support for local settings file, but you can have global settings that include common stuff for all your projects (like company name, company ID, common ignore files and other preferred settings - you can use every command line switch there). Then inside the Xcode build script you can just override those few settings that you want changed for that particular project. Or if you don't like Xcode scripts, you can do bash file you manually execute.

If there's need to have different sets of "global" settings, you can also do that with --templates cmd switch instead of using default path. But that also requires repeating template files, so it's not exactly what you want...

I was also thinking of having local settings file. In fact I think it's not much work as support is already there in code for handling global settings. To have it versatile I think this could be implemented through command line switch for passing exact location of the settings file and also check current dir for a AppledocSettings.plist file or similar. Then the order of handling settings would be:

  • Factory defaults
  • Global settings (if found)
  • Current dir settings (if found)
  • local settings cmd switch (if supplied)

To keep the same logic, local settings would simply use the same layout as global settings.

Carter Allen

I'll just chime in and say that this would be extremely helpful. I distribute an open-source framework, and if people are going to be able to generate the docs themselves, I'd like it to use the same settings that I do. And using a ton of command-line arguments seems like a messy way around this, honestly.

Dave DeLong

CarterA has the same reason I do for wanting this. I also work on a framework and I'd like to include generateable documentation. Ideally, the user would be able to cd to the folder and type appledoc . and have everything build properly.

tomaz
Owner

Thanks for explaining reasoning behind - it helps at giving better direction when planning and implementing the feature a lot!

I'm currently working on #66, afterwards I have plans to implement this. I think my proposal at the top would cover such an use. The only thing not implemented now is passing input paths through settings file. In any case you would have to include template files within your distribution and use --templates inside your settings file to have appledoc pick them up. Or rely on your users to install templates in default locations.

Also make sure you override ALL settings you care about in settings file otherwise users may use different values from global templates in case they already use appledoc - it would only affect few users, but I imagine it would be very difficult to track it down :)

tomaz
Owner

Started work on this. appledoc . or appledoc path/to/dir is certainly possible:

  • Any dir given on command line, would be checked (non recursively) for AppledocSettings.plist file. If found, it would be used as local settings.
  • Any .plist file with any name would be used as local settings.

The second case is straightforward, but first has some potential twists in it: given a dir, it should also be considered as potential candidate for source files searching: settings file would allow adding any number of paths to be scanned for source files (relative to setting file itself). I guess if at least one search path is specified in settings file, original path from command line should be ignored to prevent unexpected results. If settings file doesn't contain any search path, the original path would also be used. But if there additional search paths from cmd line, the one with .plist file should probably be ignored as search path... Any thoughts on this?

In both cases any command line switch would still have highest priority and would override local settings.

tomaz
Owner

Implemented project settings. Closed by c00f12c.

There are several ways of adding project settings:

  • Add AppledocSettings.plist file to one of the paths given to appledoc on command line. If the file is found in a path, it's settings are automatically injected. The same path is also used for source parsing. This allows command line like appledoc ..
  • Add specific path to a file with arbitrary name and .plist extension. The settings from the file are injected, but the file is not used for parsing.

In both cases, the .plist file has the same syntax as global settings file, except that project settings allow additional option --input, which should be an array of strings, each pointing to a source file or directory. These paths can be relative to the .plist file or absolute (will update online documentation soon with examples). The input option is optional; if not used, command line is expected to have at least one source file or directory.

tomaz
Owner
tomaz
Owner

Just pushed update dc9d49f8bf0dfdaf8084 containing a fix for handling --templates option in project settings, now supporting paths relative to plist file itself. Also check online documentation with basic instructions.

tonklon tonklon referenced this issue from a commit in tonklon/appledoc
tomaz Implemented project settings. Closes #67.
There are several ways of adding project settings:

- Add AppledocSettings.plist file to one of the paths given to appledoc on command line. If the file is found in a path, it's settings are automatically injected. The same path is also used for source parsing. This allows command line like `appledoc .`.
- Add specific path to a file with arbitrary name and .plist extension. The settings from the file are injected, but the file is not used for parsing.

In both cases, the .plist file has the same syntax as global settings file, except that project settings allow additional option `--input`, which should be an array of strings, each pointing to a source file or directory. These paths can be relative to the .plist file or absolute (will update online documentation soon with examples). The input option is optional; if not used, command line is expected to have at least one source file or directory.
c00f12c
This issue was closed.
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.