I would like to use ReadTheDocs to host my Sphinx documentation. The project is hosted on github. I can connect to it just fine.
The particularity that I have is that the project contains 2 Sphinx documents (e.g. a programmer's manual and a user's manual). ReadTheDocs appears to be detecting both (there are two conf.py) and building both. However when it comes to displaying them, it displays the html for only one of them, as far as I can make it, the first one alphabetically.
So my questions are:
If both have been built, how do you get to see the other one?
Is there a way to use "subprojects" to specify the path to each conf.py and hence have clear URL to each document/manual? That would be the ideal solution.
Read the Docs does not support building two different sets of documentation from the same repository and same Read the Docs project. However, you could use sphinx-multiproject extension to achieve this.
You will need to define this extension in your requirements (see https://docs.readthedocs.io/en/stable/guides/specifying-dependencies.html) and then import your repository twice under Read the Docs --one time per set of documentation you want to host: mydocs-users and mydocs-developers, for example.
Note that this is the exact pattern that Read the Docs itself uses for its documentation:
User's documentation: https://docs.readthedocs.io/
Developer's documentation: https://dev.readthedocs.io/
The repository for both sets of documentation is the same (https://github.com/readthedocs/readthedocs.org/) but documentation generated on each of the projects is defined by that sphinx-multiproject extension. See https://github.com/readthedocs/readthedocs.org/blob/6bf0bede7b757f1e9458e29ba89b591389cae4d5/docs/conf.py#L48-L63
Be sure you follow the tutorial.
Usually you need an index (in conf.py it is referred as master_doc).
Then each file must be referenced, either in a toctree or a include, or a link, etc.
Look at examples on github (ie: the Sphinx-doc repository).
Related
I'm looking for a solution that would allow us to have separate themes in the built docs through rtd, based on urls. The project is github-hosted, so we're using the Webhook integration there for rtd.
Basically, we'd like to have slug.readthedocs.io use a default, and have a custom domain through rtd, i.e. docs.ourdomain.org, use a theme styled to match our site.
on_rtd, it seems, is True whenever rtd builds the docs, so that's likely not useful, but please correct me if I'm wrong.
Perhaps multiple Webhooks? Some sphinx magic I haven't discovered yet?
Considering using branches or tags, but that just seems a bit much, and would, I believe, call for multiple project-naming on rtd. Though, again, please correct me if I'm wrong.
At the moment, we've implemented our site theming, and simply let that be in place for both, but ideally, we hope to have the slug.readthedocs.io site be more generic and in-line with the readthedocs.io feel.
At the moment, Read the Docs doesn't support multiple themes for a given repo/branch.
There are at least a couple of approaches available here.
1) Use branches to host alternative docs. Read The Docs has an example project illustrating this approach here:
Read the Docs Sphinx Theme Examples
-- [Github Repository]
2) Use sub-projects.
Neither of these really addresses the use case in my question directly, but they do offer a sort alternative approach to multiple themes.
Here's an example Sphinx doc:
https://github.com/django-tastypie/django-tastypie/blob/v0.13.2/docs/release_notes/v0.13.2.rst
I'd like commit SHA's, issue numbers, and #mentions to be hyperlinked. Anyway to do that automatically?
I'd suggest checking out the Sphinx Extension library at http://sphinxext-survey.readthedocs.org/en/latest/changelog-version-control.html.
Specifically, I believe these two extensions may provide you at least some of the support you're looking for (sans the #mentions).
https://pypi.python.org/pypi/sphinxcontrib-github
https://pypi.python.org/pypi/sphinxcontrib-issuetracker
I want to run an A/B-test or an experiment for whole part of the site. For example on my /blog/ page, where one variation would have a newsletter form and other variation a free ebook download button.
The problem is that I have to use a full URL path for the experiments, for example /blog/2013/article/1?var=1 and /blog/2013/article/1?var=2 With this method I would need create a new experiment for each blog post. This is impossible.
Any tips on how to approach this?
It's possible, but the documentation is lacking.
When you choose your variation URLs, you need to use relative instead of http://. This let's you use query parameters to define the variations, instead of the full URL. In your example, you would define your original page as:
http: //www.example.com/blog/2013/article/1
and your variation URLs would be ?var=1, var=2, etc. using relative as the option in the dropdown (instead of http:// or https://).
Here's the not-so-clear documentation on using relative URLs for your variations:
https://support.google.com/analytics/answer/2664470?hl=en&ref_topic=1745208
One important thing to remember is that if you're doing it this way, you need to include the content experiment code on every "original" page.
There's also another way to have even more control over serving the variation pages and controlling the experiment using the Content Experiments JavScript API. This is a relatively new feature - you can see the developer documentation about this here:
https://developers.google.com/analytics/devguides/collection/gajs/experiments
I am not sure this is possible. You might look at a more robust yet simple to use tool like Visual Website Optimizer or Optimizely.
if you are developing and documenting a library.. do you document every single function / data structure from every source file, or just the public ones that appear on the public header??
im leaning to the second option, is this ok?
The answer to your question depends on who is going to read the documentation. If the documentation is going to users of your API, it is probably better that you only provided them with documentation for the public interface. As this way they will not be overwhelmed by details that are not relevant to them.
On the other hand if your documentation is to be read by people maintaining the library, it should include documentation on both the public and private code.
Right now I am using a slightly different approach to arne. I have a script which copies the header files needed for the public interface to a separate directory for packaging up. This is necessary anyway for producing releases. The script also copies the Doxyfile configuration to that directory and then runs doxygen on the reduced set of files. That way I have one doxygen configuration file that I use to produce both public and private documentation.
That depends on whether you ever want to change anything in that library, say, five years from now. In that case, having documentation can come in handy. However, you should somehow separate your "private" documentation from the documentation you provide to users. This can be done by using two separate doxygen configuration files with different INPUTs.
I am trying to use Dokuwiki for creating a software user manual, given that I have to create 3 user manuals for the same product in different platform and the changes is very less. Is there any way in Dokuwiki to create a common user manual that can be used for different products?
For the specifics of DokuWiki I'd recommend the site export plugin (primarily because I made it and we use it for our documentation as well).
You can create the chapters of your book just like a normal page in your wiki. When it comes to combining them into different books, create a page called "toc" in a different namespace. In there have the following syntax (see the github page for details):
* [[namespace:chapter1]]
* [[namespace:chapter1.1]]
* [[namespace:chapter1.2]]
* [[namespace:chapter2]]
* [[namespace:chapter2.1]]
* [[namespace:chapter2.2]]
Now you can export this namespace with the roc option enabled - and merged into one document. You could also use the PDF export with custom book-like styles now (this is what we do primarily).
This answer applies to any wiki engine, not just DokuWiki.
Basically, what you need to do is factor out the common part of the documentation into separate pages that can be included in the product-specific pages. For DokuWiki this requires the include plugin (www.dokuwiki.org/plugin:include), although transclusion is often core functionality for a wiki. I'd suggest starting to write documentation for the most common product and then go back to see what portions of that can be pulled out to use for the common documentation.