As of lately, I see that the NuGet package pages include a Documentation section:
In all packages that I've checked, though, the only contents of that section is a seemingly expandable Show more item, which, when expanded, reveals to sport no further content.
As the docs do not appear to contain any hint about how that item works, I am asking here: How can I provide (presumably) package documentation for a NuGet package that will show up in that section? (And can you point out any example package that illustrates what the docs will look like on the NuGet package website?)
Notably, my packages contain the documentation XML files generated by the C# compiler from documentation comments. Yet, nothing shows up in the Documentation section, so that's not what is supposed to appear there.
The section you are mentioning is on a specific packages page on Nuget.org. For example on the RestSharp package page, this shows the Documentation near the top of the page. This section is NOT related to any package data/details. I point out RestSharp because this package does come with a readme.txt file (which is displayed after installing that package). I initially thought it might be related to the readme.txt file. However, it is not!
No, this section is only displayed when you manually configure it from the NuGet website. See the image below (taken from a package I have previously uploaded):
You can manually add text, direct the website to a file, or upload a file directly. It is in markdown format.
Related
I see the following in Nuget Manage Packages for Solution
If I am not meant to consume Microsoft.Data.SqlClient.SNI why does it show in Nuget?
The Browse tab in the NuGet Package Manager shows packages by popularity. It is used to search for a specific package:
Mircosoft Doc (link)
The Browse tab displays packages by popularity from the currently selected source (see package sources). Search for a specific package using the search box on the upper left....
In your case, you are searching for "Microsoft.Data.SqlClient", which starts with the same string like "Microsoft.Data.SqlClient.SNI" and I guess, it has a high rated popularity.
I am trying to link two doxygen html documentations. To this end, I generated the first documentation for package A using GENERATE_TAGFILE, then I set in the Doxyfile of package B TAGFILES = "pathtotagfile = relpathtodocumentation". This seems to work properly, since there are no warnings. However, I the connection of the two packages is not as deep as I would like it to be.
Using doxygen 1.8.13, I only see links to the external files. Can I configure that classes and namespaces also list external stuff? I have set ALLEXTERNALS, EXTERNAL_GROUPS and EXTERNAL_PAGES to YES, but still I only see external files.
Using doxygen 1.8.4, external packages appear under Related Pages, but this seems to have been changed. I would have appreciated this. Can I reenable it in the latest version?
I also welcome hints at how Link to external documentation works. The doxygen help is a bit short here.
So I have a collection of projects that are documented with doxygen (and it has to be doxygen). I run doxygen separately for each project and use the "linking to external documentation" http://www.doxygen.nl/manual/external.html in order to connect the documentation. For example I import the tagfile for a library project in another project where it is used. This way links to the library classes are automatically generated when they are used in the other project documentation.
Now for the problem, say I have a library libA that is used in another library libB. libA and libB have a main page each. In the documentation of libB I import the tagfile for libA. So far so good, but now I have a third project, lets call it app, which uses both libA and libB. I import both tagfiles and links works for both, BUT it also complains that libA main page anchors are duplicate. I realise they are, since they are imported both through libB and as libA directly, however if I don't import libA tagfile in app then links for libA classes are not created.
Now the resulting documentation seems to be fine if I just import both tags and ignore the warnings, but the warnings will clutter the log file so I might miss some other warning for example that I forgot to document a method or something.
So, any ideas how to solve this? Is this a bug in doxygen? Can I suppress this specific warning? Is there a better way to document a collection of projects like this with doxygen?
I'm no expert, but I think you could get around this problem by running doxygen twice for libB. The first time, set GENERATE_TAGFILE but not TAGFILES, so that the generated tagfile is just for libB. Then modify the Doxyfile to link the libA tagfile as normal through TAGFILES, but disabling GENERATE_TAGFILE so that you don't overwrite the clean version of the libB tagfile.
If it behaves like it should, you'll get a tagfile just for libB with no references to libA that you can use when running doxygen on app, but the actual html documentation for libB will properly link to the documentation for libA.
I have published a couple of NuGet packages (.NET class libraries). The packages include XML documentation file for each DLL. All packages are published on www.nuget.org and www.symbolsource.org.
Now, is there a website/service which will automatically generate (and host) documentation for my packages? I am picturing some sort of mini-site for my packages, where users can see all class definitions, their methods and related documentation from the XML file (basically something like MSDN but for my package)?
Ideally every time I publish a nuget package, I want to be able to go to www.SomeNugetDocumentationSite.com/packages/MyPackage and see MSDN-like documentation for my packages.
Thank you.
I have noticed that nudoq.org does such thing for my Pkcs11Interop package. I have never registered there or anything like that so I guess they are generating documentation from XML file which is present in the package.
However I still prefer to generate documentation with doxygen (which by the way uses the same inlined XML comments present in C# source code) and host it by myself because this way I can fully control the result.
I use javadoc to document my classes and methods. I would like to add some overview information to my packages, too. I like how Eclipse creates a stub of a matching Doc Comment for each class or method once I type /**<Enter>. Does Eclipse have an easy way to generate a package.html file, too?
Update 4 years later (Oct. 2013)
javabeangrinder's answer (upvoted) mentions the following trick:
To create a package-info.java file in an existing package:
Right click on the package where you want a package-info.java.
Select new->package.
Check the Create package.info.java check box.
Click on Finish
Original answer (May 2009)
There is no template or wizard to easily create a package.html file.
As mmyers said in his comment, since Java1.5, the correct file to create would be package-info.java.
That file can be used not only for javadocs, but also for package-level annotations (as illustrated here).
There is an opened Bug (#86168) for demanding a wizard for the creation of package-info.java (since the class wizard does not allow the package-info name).
The reflections on that topic are on since... 2005! The problem is that any solution should
be implemented in a way that it also helps with 1.4 code.
The current workaround is to create a package-info.java as a text file.
From that point forward, package-info.java behaves as a normal Java class, and Eclipse places a package-info.class file in the output folder.
The Javadocs are correctly built using package-info.java, and not the package.html file.
(source: developpez.com)
Note (in response to Strawberry's comment):
bug 77451 (2004!, for package.html)
bug 163633 and bug 163926 (2006, for package-info.java)
both wish a preview of the package overview in package-info.java in the Javadoc
view.
So far, no patch has been proposed/implemented.
There is simply not enough demands for that feature to be added.
In eclipse
Since package-info.java isn't a valid identifier for a class it cannot be created as a class in Eclipse.
I found that when you create a new package there is a check box to check if you want a package-info.java.
To create a package-info.java file in an existing package:
Right click on the package where you want a package-info.java.
Select new->package.
Check the Create package.info.java check box.
Click on Finish
The JAutodoc plugin does a great job of this, as well as all your other documentation needs. Install and configure the plugin and right click the package and click JAutodoc > Add Package Javadoc
There are configurations and templates available for the .java or .html package documentation.
This plugin also does a great job of standardizing all your Javadoc needs, with a great deal of customization.
http://jautodoc.sourceforge.net/
There's a plugin that seems to create package.html files. I haven't used it but someone landing here might find it useful.
http://sourceforge.net/projects/package-javadoc/