My primary documentation for a project is Sphinx. I also have a large amount of JavaDocs that I'd like to integrate. The basic setup is:
sphinx_source/
javadocs_built/
Before building the Sphinx documents, I can copy the JavaDocs into a directory under sphinx_source.
How can I reference this directory with non-reST files in it from within Sphinx and have them be brought along during the build process?
You probably need to reference the files using the :download: directive.
See: here.
Note that you'll need to reference the files individually, so you may want to set up some kind of script to generate the references for you.
Related
I have my visual studio 2022 project with c# and I want to create the documentation but I don't want more files and folders to my project.
Docfx create folders and files.
SandCastle you even have to create another project inside your solution.
There is a way to run a command and generate the web page without creating any extra file in the project/solution?
Thanks.
If you are just wanting to generate documentation from your source code xml comments than DocFx does not require that many new files to be be checked into source control. Sure you will need the basic project structure but all the intermediate / generated files in the output can be excluded from your committed source code using .gitignore files (assuming you are using git).
For example, in these tutorials
https://dotnet.github.io/docfx/tutorial/walkthrough/walkthrough_create_a_docfx_project_2.html
https://dotnet.github.io/docfx/tutorial/walkthrough/walkthrough_create_a_docfx_project.html
You would only really need
docfx.json
index.md
toc.yml
api/index.md
api.index.yml
.gitignore
If you add the following lines to the generated .gitignore from tutorial 1 then all the intermediate and generated documentation yml files will never be committed to git.
api/*.yml
api/.manifest
Hopefully this helps, I know it does not get you 0 extra files like you asked but its a fairly light weight solution to generating api documentation.
In our team we have several Projects, each separately documented with Sphinx.
We want to have a central documentation page, which includes all of our projects.
Of course we could build a HTML page with links to the different documentations.
Is there a way to combine the documentations with Sphinx itself?
Maybe with a separate Documentation project, which somehow includes the documentation from the other projects?
You could try intersphinx to create links between existing documentations. This works like Wikipedia links to other Wikis in the Wikimedia universe.
An alternative is to checkout all documentation directories into a new repository. You might need to create new toctrees because it either doesn't fit into the overall structure or the nesting gets to deep. Therefore you could provide alternative index files by changing the index file name to e.g. master.rst.
An individual documentation is build by using the original index.rst but if it's used in the master documentation, only master.rst files will be considered as toctrees.
In my Gradle script, I have created a Javadoc task that generates documentation for my java files and for the auto-generated R.java, so that it creates links for my XML resources. I am using Doclava and even the #attrworks as expected when referencing XML resources.
However, when I add comments in my original XML files in order to document them, they are lost in the process of generating the R.java file and they are replaced by the default documentation.
Is there a way to document my XML resources and make the documentation appear in the resulting javadoc?
The tutorial http://sinnerinc22.blogspot.de/2010/07/adding-syntax-highlighter-to-jamwiki.html describes how to enable syntax highlighting in JAMWiki.
My problem is that in the recent version of JAMWiki v1.2 the two files to be modified WEB-INF/jsp/top.jsp and WEB-INF/jsp/close-document.jsp do not exist any longer...
There is a third-party syntax highlighting tag extension available with JAMWiki 1.2 link that may work for you
I have added SHJS to my installation just following SHJS instructions rather than JAMWiki instructions. Simply edit JAMWiki JSP pages to add content as documented here. To see how does it work, look into the source code of this HTML document.
You even do not need to compile anything after you edit JSP, the server does this for you automatically.
Following up on Audrius's answer, here's exactly what you need to modify.
./jamwiki.war/WEB-INF/jsp/topic.jsp Modify it to look like this
Download the SHJS zip and copy all of the individual files from ./css/, ./lang/, ./sh_main.js, and ./sh_style.css from the zip to JamWiki.war/shjs/. (This will flatten the directory structure so everything is now in ./shjs/. Flattening the structure is optional but it makes for easier paths when referencing them in the jsp.)
You can modify the .war with 7zip or dig into your web app container file system and place the JSP and shjs folder directly.
Redeploy or refresh as needed depending on your preferred edit method.
I'm pretty new to Sphinx, documenting my project on a server. Now a co-worker sees what I've been up to and she wants to do the same thing--document her project on the same server.
The projects are not related (they don't belong in a single TOCtree) and I don't know how to help her. Can I configure sphinx to build separate document trees? Is it as simple as making two copies of the Makefile and have it set different source/build directories?
thanks,
--Tim
Yes, I think you want to treat them as separate projects. For that you should just copy the current build tree as you stated, and edited the config.py file. The other options is just to start from scratch by running sphinx-quickstart.
Also, keep in mind that you can reference topics between the two documents by using the Intersphinx plugin.