I have a project supported in Travis-CI. I want to generate the documentation using Doxygen but Im not sure how to make it. I already have a Doxyfile in the root of the Github project. How can I do it?
Thanks in advance for your help.
I don't know whether or not you are on a commercial plan for Travis-CI or are using it for free for a OSS project. In the later case be aware of their new pricing policy.
You didn't mention the OS for which you want to run doxygen, for some distributions an installation package is available.
To run doxygen you have to install doxygen (or build it on Travis, but this would be a bit of an overkill). After installing it you should be able to run doxygen right out of the box.
I got this error when converting a ipynb file to latex. Looks like there's a hardcoded upper bound on pandoc in nbconvert. Is there any reason why it would work with the latest version?
nbconvert/utils/pandoc.py:52: RuntimeWarning: You are using an unsupported version of pandoc (2.2.1). Your version must be at least (1.12.1) but less than (2.0.0).
Many command line options have changed between pandoc v1.* and pandoc v2, e.g. --smart is no longer recognized as pandoc uses a finer-grained mechanism now. In general, it seems like a good idea to limit the acceptable version.
That being said, nbconvert seems to only use options which have not changed; it is probably save to bump the upper version bound.
I'm trying to visualize a code base without explicit doxygen comments, I run into what seems like an error when viewing the dot graphs in the html generated by doxygen Generated Boxes
I'm running doxygen under a cygwin bash with GraphViz installed. Any Ideas?
OK, figured it out...the blank boxes should have been a dead give away that the problem was with a missing font dependency. I installed a different version of GraphViz that had the font dependency resolved under mingw.
I've authored the README file in my Perl module in Markdown. Github treats this README file as plain text. I tried renaming the file to "README.md"—which looks great on Github, but is invisible to Perl tools that look for a file named "README."
Is there any way I can have both a README file, and have my Markdown formatting be interpreted correctly by Github?
The only option I could come up with was to have both a README and a README.md, but I'd prefer not to have to manually keep the two files in sync.
Thanks for your help.
Format your README in pod, rename it README.pod and then it works both places! Example
For my purposes I actually just generate my README.pod from the main pod by doing
$ podselect lib/My/Main/Module.pm > README.pod
One caveat, named external links don't work correctly L<GitHub|http://github.com> will unfortunately point to search.cpan.org looking for a GitHub module. I have tried to inform them of this glitch but it got me nowhere. Instead you can just use plain external links (i.e. GitHub: L<http://github.com>) and they work fine.
Good news, it appears that they have fixed this since the last time I checked!
Just a question, what parts of the Perl toolchain expect a README file? If you mean including it in your tarball, just be sure to add the file to your MANIFEST and it should get included.
Have you heard of POD? This is the standard documentation tool in Perl. POD is a simple text documentation format that actually lives in your code. One of the commands that come with perl is perldoc. You can use it to get the information of any Perl command. Try these:
$ perldoc File::Find
$ perldoc -f split
All Perl modules in CPAN are required to incorporate POD documentation. In fact, this is how the CPAN webpages themselves are built.
So, where am I going with this and how is this going to help you?
You should include POD documentation in your Perl program. Then, you can use the pod2text command to create your README for your Perl program:
$ pod2text myperl.pl > README
That handles half of your issue.
The other half is a bit more tricky. You need to install from CPAN the Pod::Markdown on your system. Then, you can run the pod2markdown command that comes with this module to create the markdown version of your file:
$ pod2markdown myperl.pl > README.md
The results:
Your documentation lives, as it should, in your Perl program.
Users can use the perldoc program to print out complete documentation of your program.
You can use the pod2text tool to create your README file.
You can use the pod2markdown tool to create your README.md file.
As a bonus, you can use the Pod::Usage module that comes with Perl to show the POD documentation (or bits and pieces of it) as help text that's displayed when a user runs your program with the -help parameter.
So, one place where your documentation lives, and you're using a couple of helper programs to create the files Github and whatever Perl tools you use need.
If you don't mind using Dist::Zilla you can pretty much do away with maintaining a README entirely. For example Dist::Zilla::Plugin::ReadmeFromPod can create your README file by extracting the Pod from your main module. This means never having to write a README again.
I've never tried it myself, but you could look at something like Dist::Zilla::Plugin::ReadmeMarkdownFromPod to create your README automatically in markdown.
This may not be the exact answer you're looking for, but I think using this sort of a tool can save you a lot of time as it allows you avoid repeating yourself in your documentation.
Another solution if you really want to distribute your module with a Markdown README, that doesn't involve Pod is to :
rename your README file to README.md
update the previous change in the MANIFEST file
I think it can be an interesting solution because more people know Markdown syntax than Pod one. As the aim of the README file is to be read by anyone, Markdown should be considered.
I was just looking for a solution for this problem and decided to use Dist::Zilla::Plugin::ReadmeAnyFromPod as it understands =attr and =method tags from Pod::Weaver.
The only option I could come up with was to have both a README and a
README.md, but I'd prefer not to have to manually keep the two files
in sync.
Then automatically keep them in sync?
I would like to include a content file into the package that should refer to the current version of the package being installed (more precisely to the package folder, but the only varying part is the version).
Is there a special syntax (e.g. $packageversion$ - does not work) to include the version number into a transformed (.pp) content file?
Alternative: I can access the version from the install.ps1 and I can also invoke Add-Content (i suppose that will also apply the transformations), but how can I extend the replacement placeholders?
The variables you can use (like $rootnamespace$) are the ProjectProperties so you won't be able to access the version number.
As a workaround, you could try naming the file as part of your build step that creates the NuGet package.
If you think it'd be good to see this added to NuGet, it's worth starting a discussion on the NuGet site, the developers are pretty active there :-)