Can phpDocumentor be used to generate HTML docs for some legacy code that does not necessarily conform to its standard?
I'd like to generate some preliminary documentation for an old code tree and later on start improving my comments and add the appropriate # tags as I get fluent with phpDocumentor. I've never used this piece of software before and the examples I've found focus on how to write new code that conforms to its syntax and generate HTML file by file with the -f parameter.
I've installed latest phpDocumentor through the PEAR command line installer and tried this little *.bat file on Windows XP:
#echo off
phpdoc ^
--directory "\\server\project\trunk" ^
--target "C:\tests\project-doc"
... but this is all I get:
PHP Version 5.3.5
phpDocumentor version 1.4.3
Parsing configuration file phpDocumentor.ini...
(found in C:\Archivos de programa\PHP\pear\data/PhpDocumentor/)...
done
Maximum memory usage set at 256M after considering php.ini...
using tokenizer Parser
directory: '' not found
I've also tried mapping the UNC path to a drive letter:
#echo off
phpdoc ^
--directory "I:\" ^
--target "C:\tests\project-doc"
... but:
PHP Version 5.3.5
phpDocumentor version 1.4.3
Parsing configuration file phpDocumentor.ini...
(found in C:\Archivos de programa\PHP\pear\data/PhpDocumentor/)...
done
Maximum memory usage set at 256M after considering php.ini...
using tokenizer Parser
a target directory must be specified
try phpdoc -h
This error message is the same if I create "C:\tests\project-doc" before.
What's exactly wrong in my syntax?
phpDocumentor can indeed run against "undocumented" code. It builds its docs based on the code itself, and uses the docblocks as additional info (and additional organization, in the case of #package and #subpackage tags).
I'd suggest starting with phpDocumentor against your existing code, and work towards clearing out the warnings you see in the errors.html file that results -- this file is generated in the top level of your output docs, but there isn't any link to it from the output docs.
Once you have those cleared, you can start running phpDocumentor with the -ue argument (--undocumentedelements), which will add new warnings to errors.html, highlighting (in much greater detail) things that still need to be documented in docblocks.
Now, as for the issue you're having trying to run the program against code on a shared drive, I'm not sure what's wrong there. The script is clearly able to execute PHP and find the phpDocumentor code itself. You might try putting the arguments in the same line, rather than using the ^ as a line-feed escape character, and perhaps remove the quotes around the paths (since no spaces exist in the paths).
I think I've found what the issue is. The parameter parser is very picky and it doesn't like neither UNC paths nor bare root directories. If I replace this:
--directory "I:\"
... with this:
--directory "I:\."
... it finally starts running.
I suppose it's a bug. Their bug tracker doesn't seem to be public so I don't know if it's a known issue.
Related
(Before downvote im aware how to do this using code thats inline to this command but not how to do it using a file that uses the --app="data:text/html,<sometags></sometags>)
How would I open a local html (mar.html) file using this command
C:\'Program Files (x86)'\Google\Chrome\Application\chrome.exe --profile-directory="Default" --app=
Specifically, the issue is my lack of familiarity with the --app flag
I tried
C:\'Program Files (x86)'\Google\Chrome\Application\chrome.exe --profile-directory="Default" --app="mar.html"
C:\'Program Files (x86)'\Google\Chrome\Application\chrome.exe --profile-directory="Default" --app="file:///mar.html"
Both don't work.
Giving me the error
Your file was not found
It may have been moved or deleted.
ERR_FILE_NOT_FOUND
You almost got it. The file descriptor path must be absolute and encoded.
Encoding the path correctly with cli tools like "urlencode"(gridsite-clients) did not work for me.
If you have NodeJS installed and would use a linux machine, you could use this command.
chromium --app=`node -e "console.log('file://'+encodeURI(process.argv[1]))" "$(realpath "/path/of/your/file.html")"`
This works also fine with relative paths.
For windows you have to rewrite this yourself.
I have unsuccessfully been trying to install some plugins for VIM for sometime. I have mostly been following the information in this reference. I've basically just been dropping the plugin files in various directories hoping something works, nothing has yet. I have a .vim directory at the following path:
/Users/{my_user_name}/.vim
I have tried adding my files to the directory above as well as a directory inside it called plugins. Can anyone suggest what I might be doing wrong?
When I enter
:help 'rtp'
I get
Unix: "$HOME/.vim,
$VIM/vimfiles,
$VIMRUNTIME,
$VIM/vimfiles/after,
$HOME/.vim/after"
Amiga: "home:vimfiles,
$VIM/vimfiles,
$VIMRUNTIME,
$VIM/vimfiles/after,
home:vimfiles/after"
PC, OS/2: "$HOME/vimfiles,
$VIM/vimfiles,
$VIMRUNTIME,
$VIM/vimfiles/after,
$HOME/vimfiles/after"
Macintosh: "$VIM:vimfiles,
$VIMRUNTIME,
$VIM:vimfiles:after"
The correct location is in a plugin subdirectory (not the plural plugins):
/Users/{my_user_name}/.vim/plugin/*.vim
You can check your actually used path with
:set rtp?
The trailing ? means query value, don't set. (:help rtp is just the general documentation, not what's actually used.)
The useful :scriptnames command will tell you what actually got sourced.
Note that all these instructions are valid for plain *.vim plugin scripts; some plugins are also distributed as (*.zip, or *.tar.gz) archives, or the Vim-specific Vimball (*.vba, *.vmb), which typically contain the subdirectory structure already.
For an hypothetical single-file plugin:
~/.vim/plugin/plugin.vim
For an hypothetical multi-file plugin:
~/.vim/autoload/plugin.vim
~/.vim/plugin/plugin.vim
~/.vim/doc/plugin.txt
If that hypothetical multi-file plugin comes with documentation, run the following command to add it to the :help index:
:helptags ~/.vim/doc
The :scriptnames shows you a list of sourced scripts.
Also, most plugins have some kind of README that details recommended installation procedures: read it.
I've been trying to get a custom template to work with PHPDocumentor (2) without much luck. The documentation on their site is incomplete and I'm kind of stumped.
What I've done is downloaded a copy of a complete template and reference it in my command, like so:
php phpdoc.php
--template=/path/to/customtemplate/
-d /path/to/php/source/files
-t /path/to/generated/content/
The command runs fine: it generates the documentation correctly but appears to be ignoring the --template option - at least, any changes I make to the template files in the /customtemplate folder are ignored.
Anyone have any idea?
(Thanks in advance!)
Ben
Instead of declaring the template command on the CLI you might try changing your phpdoc.dist.xml configuration file so that it pulls the template name or path from there directly.
After wasting some time to figure out what goes wrong, I finally have to ask for help. I want to use appledocs from Gentle Bytes. I followed every step of the quick install guide, but I´m not able to compile the project.
Here is what I´ve done:
1. cloned it from git://github.com/tomaz/appledoc.git
2. installed the templates to ~/Library/Application Support/appledoc
3. tried to compile the project
Everytime I try to compile, I get following error:
ERROR: AppledocException: At least one directory or file name path is required, use 'appledoc --help'
What do I have to do now?
Sounds like you've compiled it just fine and are now running the program. If it's a command-line program try command-option-R in Xcode to provide some arguments (i.e. names of files that you want to process).
The error means you didn't give it source paths: after all switches, you must give it at least one path to your source files. Can be either file or directory. In later case it will recursively scan the dir. Here's example
appledoc <options> ~/MyProject
Above example will use ~/MyProject directory as a source. You can also add multiple source paths. Note that you need to give the tool few options, see this page for minimum command line and other usage examples.
You either have to copy appledoc executable to one of directories in your path, as suggested by Caleb, or use full path to it when invoking (for example: /path/to/appledoc)
I searched the net and handbook, but I only managed to learn what is the masked package, and not how to install it. I did find some commands, but they don't seem to work on 2008 (looking at it, it seems those are for earlier versions). I have something like this:
localhost ~ # emerge flamerobin
Calculating dependencies
!!! All ebuilds that could satisfy "dev-db/flamerobin" have been masked.
!!! One of the following masked packages is required to complete your request:
- dev-db/flamerobin-0.8.6 (masked by: ~x86 keyword)
- dev-db/flamerobin-0.8.3 (masked by: ~x86 keyword)
I would like to install version 0.8.6, but don't know how? I found some instructions, but they tell me to edit or write to some files under /etc/portage. However, I don't have /etc/portage on my system:
localhost ~ # ls /etc/portage
ls: cannot access /etc/portage: No such file or directory
There are two different kinds of masks in gentoo. Keyword masks and package masks. A keyword mask means that the package is either not supported (or untested) by your architecture, or still in testing. A package mask means that the package is masked for another reason (and for most users it is not smart to unmask). The solutions are:
Add a line to /etc/portage/package.keywords (Check man portage in the package.keywords section). This is for the keyword problems.
Add a line to /etc/portage/package.unmask for "package.mask" problems (you can also use package.mask for the converse). This is in the same man file, under the section package.unmask. I advise to use versioned atoms here to avoid shooting in your own foot with really broken future versions a couple of months down the line.
These days there's also a more 'automated' solution, called "autounmask". No more file editing needed to unmask!
The great benefit of the package is, it also unmasks / handles keywords of dependencies if needed. It's provided in the package app-portage/autounmask.
/etc/portage/package.keywords and
/etc/portage/package.unmask
can be directories as well nowadays (but autounmask handles single files as well). In those directories, multiple can place multiple "autounmask" files, one file in each dir per "unmask"-package. If you use single files instead of dirs, 'autounmask' will place some kind of header / footer, and this way it becomes easy to remove "unmasks" if wanted.
Simply mkdir /etc/portage and edit as mentioned here: http://gentoo-wiki.com/TIP_Dealing_with_masked_packages#But_you_want_to_install_the_package_anyway...