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.
Related
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.
I currently began a new project with processing and first started with the
processing-ide that comes together with the installation.
Is it possible to structure the project into subdirectories instead of having to put all classes into the single sketch folder? I looked at the documentation at https://processing.org/ but didn't find any useful information about how to divide projects into manageable source subdirectories. Your help is much appreciated :)
No the default Processing IDE does not support this.
Before switching to another IDE for Processing, keep in mind that Processing 3 will highly focus on creating an entirely new IDE, which "might" add this functionality.
Is there a list of all (or nearly all) possible issues that could stem from maintaining multiple solution files for the same set of projects? The only reason for doing so is different versions of Visual Studio.
I'm aware of the glaring issue where new projects are added in one solution file, that haven't been synced to the other. What are some others?
disclaimer: my current company is still entrenched using VS10, for mainly political reasons. so please, save the preaching about the need for having a single solution and how this is not the optimal "solution".
I've seen this done all the time, for the most part it is perfectly fine other than what you mentioned, any files added would have to be added to all of the projects. However, I would recommend you go with a make file of sorts, CMake is a very robust version but there are plenty of others. The way they work is basically, you write one script that defines how the project is to be made, then the end-user runs CMake.exe on it. It will take that script and generate the proper solution and project files for your entire project in the version of VS you want, it also supports generation of types like XCode and Eclipse solutions etc so it is very multi-platform.
I have created three different solutions for three different clients, but those solutions are for an app that have the same features, classes, methods, resolution, except for the images, XML resource files, and a web service reference, that are specific for each one.
I would like to have just one solution for all those apps, that I could open in VS2010 IDE for edition, without errors. So, when I need to build or publish an specific app, I just set the client which one I need to, and go ahead to building or publishing.
It is important to consider that XML file names will be the same, as classes and images names too. The difference will be the content, but the name will always be the same.
My intention is to reduce my effort to maintain many solutions, having just one solution to work with.
In my company, we will have more than those three clients soon, so I am worried about how to maintain that. The best way will be have just one solution and when I need to generate a new app for a new client, I have just to change/include a few things (like some resources and images) and compile to a new client folder.
Is it possible? If so how?
One option would be to have a master solution which had the following
A "Template" project that contained your actual application and all of the shared code
Projects for all of your clients
In the projects for your clients, you could have links to the files in your files that come from your shared project. Then, in each of those projects, you could add the files that are only specific to them.
With this kind of structure, whenever you made a change to your Template project, all of the client projects would be updated as well because they just have pointers back to the Template project.
A good reference for this kind of setup would be the Json.Net Code Base. There he has a solution and project for all of the different configurations, but they all share the same files.
In terms of ensuring that the xml files are named properly, you might just want to put some checks into your main application to ensure that it has all of the files needed or potentially add a check into your build process.
There are many ways you could look to tackle this.
My favorite would be to run some sort of pre-build step - probably outside of Visual Studio - which simply replaces the files with the correct ones before you do a build. This would be easy to automate and easy to scale.
If you are going to be building for many more than three customers, then I think you should look to switch from Visual Studio building to some other automated build system - e.g. MSBuild from the command line or from something like TeamCity or CruiseControl. You'll find it much easier to scale if your build is automated (and robust)
If you don't like the file idea, then there are plenty of other things you could try:
You could try doing a similar step to above, but could do it inside VS using a pre-Build step.
You could use Conditional nodes within the .csproj file to switch files via a project configuration
You could look to shift the client-specific resources into another assembly - and then use GetResourceStream (or similar) at runtime to extract the resources.
But none of these feel as nice to me!
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