markhoeber / sublime_sphinx_guide

Sublime and Sphinx Guide

RST, Sphinx, Sublime, and GitHub

This repository contains documentation for using RST, Sphinx, Sublime, and GitHub to build documentation.

Contributions are more than welcome.

sublime_sphinx_guide's Issues

How to generate different TOCs for subdirectories within the same project in Sphinx

Following the instructions about conditional text in Sphinx, I created three different build subdirectories in one project to generate three custom contents from the same source (e.g. source-file -> output1 for users, output2 for admins, output3 for developers).

I'm currently stuck on how to generate three different TOCs for each subdirectory within my project.
In the current scenario, the build command generates a single TOC for all three subdirectories and overwrites the former TOC.

My project consists of a single source directory and three different build directories. My tree structure looks like this:

C:.
|   make.bat
|   Makefile   
+---adminbuild    # Build directory for admins        
+---build         # Build directory for users
+---devbuild      # Build directory for developers
+---env           
\---source
    |	conf.py
    |	contents.rst
    +---pics
    +---_static
    \---_templates
            index.html
            layout.html

As you can see, I have a custom landing page in the _templates folder (i.e., index.html), and a Jinja template (layout.html) extending my default layout.

Here's an extract of my conf.py:

# The master toctree document. Tell Sphinx about the location of our table of contents.
root_doc = 'contents'

# Tell Sphinx that we still want to generate the index page, but with a custom template.
html_additional_pages = {'index': 'index.html'}

Is there a possibility to set multiple values for the root_doc and specify each path within the corresponding subdirectory, or any other workaround to achieve this?

Thank you for your help!

Builder name **** not registered or available through entry point

Are the changes to Makefile still valid?
Because I think Sphinx changed his Makefile.

To me Add link/Test links, Internalhtml and Livehtml don't work:

>>> make link
Running Sphinx v5.0.2

Sphinx error:
Builder name link not registered or available through entry point

Also I use Windows10 and I have make.bat, you don't. Should I change something there?

Or maybe in conf.py?

Here more details or you can ask me because I'm not sure what can be useful.

Thank you

Btw, good guide!

multi paragraph notes

Just realised that on readthedocs the sphinx doesn't follow the syntax shown here:
..note::
Paragraph 1

Paragraph 2

Paragraph 3

doesn't work. None of the paragraphs is displayed as a note. So, what is the real way to create a multi-paragraph note?

Example: https://jscan-docs.readthedocs.io/en/latest/general/key_programming.html#how-to-program-a-key
The first three paragraphs should be a note block. They are rendered as plain text.