documentation

I am using Sphinx to document a webservice that will be deployed in different servers. The documentation is full of URL examples for the user to click and they should just work. My problem is that the host, port and deployment root will vary and the documentation will have to be re-generated for every deployment. I tried defining substitutions like this: |base_url|/path .. |base_url| replace:: http://localhost:8080 But the generated HTML is not what I want (doesn't include "/path" in the generated link): <a href="http://localhost:8080">http://localhost:8080</a>/path Does anybody know how to

Any suggestion how I can document my Perl code? What do you use and what tools are available to help me? Which module do you use to convert pod to html? Look inside almost any Perl module and you'll see the Plain Old Documentation (POD) format. On CPAN Search , when looking at a module you have the option of viewing the raw source, so that's one way you can look at the raw pod, but you can also use perldoc from the command line. The -m switch shows you the file perldoc -m Foo::Bar Or, if you want to find the file so you can look at it in your favorite editor, use the -l switch to find it:

Is there a reason to include both @version and @since as part of a class? They seem to be mutually exclusive. Also, what does %I% and %G% mean, and how to set/use them? @version %I%, %G% Thanks dhable The @version tag should be the current version of the release or file in question. The %I% , %G% syntax are macros that the source control software would replace with the current version of the file and the date when the file is checked out. The @since tag should be used to define which version you added the method, class, etc. This is your hint to other developers that they should only expect

I'm trying to add cross-references to external API into my documentation but I'm facing three different behaviors. I am using sphinx(1.3.1) with Python(2.7.3) and my intersphinx mapping is configured as: { 'python': ('https://docs.python.org/2.7', None), 'numpy': ('http://docs.scipy.org/doc/numpy/', None), 'cv2' : ('http://docs.opencv.org/2.4/', None), 'h5py' : ('http://docs.h5py.org/en/latest/', None) } I have no trouble writing a cross-reference to numpy API with :class:`numpy.ndarray` or :func:`numpy.array` which gives me, as expected, something like numpy.ndarray . However, with h5py, the

NDoc has an XML element inheritdoc which allows you to inherit documentation of a member from the parent class (or an implemented interface). However, Visual Studio (i.e. the C# compiler) does not understand this tag and complains about the documentation not being present or complete. So does StyleCop and some other tools. Is there an alternative approach? How do you go about keeping the docs complete, yet without duplicating the XML descriptions? One alternative is to use GhostDoc - an add-in for Visual Studio that automatically generates comments for you. This duplicates the XML description

Latex-to-html converters I've seen in the past have been pretty awful. Editing raw html is no fun and doesn't seem to translate well to the printed page. How do others solve this problem? Links to examples (both pdf and html) would be great. Added: Another similar question was just asked: What formatting language should I use for project documentation For documenting code, I also recommend Sphinx. ReStructured Text is nice because it is readable and somewhat marked up in plaintext, and can do a nice job converting to html and to pdf. I still like LaTeX for certain things. My wife and I use