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.
Related
I am writing a documentation for a project that involves multiple developers. We use Subversion (SVN) to work on our code base.
I wrote the first draft of the documentation document using HelpNDoc, which I like for the nice tree-view and easy of use; the problem is that there is a single file, so I don't know how to use SVN to allow other developers to contribute to the documentation and update it.
Do you know if it's possible? If not, can you advice a nice software, easy to use, with a tree-view of the documentation that can be used with SVN or makes it possible for multiple users to update it? We use Windows.
HelpNDoc projects are binary files based on the SQLite open source database engine. The advantage is that the whole documentation stored in a single file so it can easily be copied, moved, shared, backed-up...
However one drawback is that it has to be checked-in as binary content in any version control system including Subversion: diff and merge are not possible on those files.
One possible solution would be to use external documents in HelpNDoc's library: each user works on her own document (which can be a Word document, and HTML web-page...) and a master HelpNDoc project is created to include those documents at generation time. See "Include a file at generation time" in the following step by step guide: How to add an item to the library
Amount of files doesn't matter, real format (text/* or binary) - does. If SVN|any VCS can merge two HelpNDoc files with diverged history (just try it by hand), you'll be happy
I once used Helpinator for software documentation, it's pretty close to HelpnDoc but it's storage format is more suitable for version control.
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.
I have many bundles (let's say hundreds) and it is quite difficult to specify relation between bundles+features-distrubutions in UI. Image, at first I define all relations between bundles, features and distribution. Than I want to update some bundles... it is almost impossible to find them in current implementation of UI. They are not groupped and one list of all bundles without any search bar is really hard to work with.
Is there any support for a file based solution. For example Apache ACE would watch a certain folder containing distribnution's bundles. When ever I make a change there, it would be propagate it to all targets.
There is currently no file based solution that matches what you describe, however, I think there are still a couple of solutions that might help you:
There are two types of associations between artifacts and features in ACE: static and dynamic ones. The latter can be of help to you, as they always automatically bind to the highest version of a bundle. So, once you've made all your associations, you can simply upload a set of newer bundles and the associations will adapt.
There is also a REST API you can use to programmatically talk to ACE. You can use that to further automate your process.
That said, you have a valid point that it is difficult to keep an overview when there are a lot of artifacts in the first column. I would advise you to watch, or even contribute to the following issues that were all created to improve this situation:
https://issues.apache.org/jira/browse/ACE-319
https://issues.apache.org/jira/browse/ACE-320
https://issues.apache.org/jira/browse/ACE-321
I'm building a custom dialog in Alfresco 3.4. I'd like to include a tree view as a UI control similar to the one in the Copy/Move dialog in the Document Library. Is there a call in Alfresco or an easy way to include this to drive my dialog, or is this going to be a completely custom piece?
You don't have to write your custom tree view as far as I know. But including the one that Share uses is not that easy as well, unless you have experience with webscripts, building custom pages, templates...
First check these out:
http://wiki.alfresco.com/wiki/Share_Custom_Pages
http://wiki.alfresco.com/wiki/3.0_Component_Standards
Here's where the files that you need to look at are located
The client side javascript files that Share uses are here:
tomcat/webapps/share/components/documentlibrary/
Look at the following files: tree.js, repo-tree.js or dod5015-tree.js (RM implementation)
The share webscripts are here:
tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/documentlibrary
Look at the following files: tree.get., repo-tree.get., dod5015-tree.get.*
Here's how the tree component is included in document library:
tomcat/webapps/share/WEB-INF/classes/alfresco/site-data/template-instances/documentlibrary.xml
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.