Sphinx: first steps documentation about including other documents into toctree is incomplete

[BMaxV]

Problem

I'm trying to get started with sphinx, have never interacted with .rst before.

This bit about adding elements to the toctree tells me to add new documents to the toctree by writing them in there as shown, without the .rst ending.

What it doesn't say is that these documents apparently need a title. Because sphinx-build is complaining that they don't have one. The introduction document also doesn't say how to add that required title.

Procedure to reproduce the problem

sphinx-quickbuild
echo "test" | test.rst
write "test" into the toctree
sphinx-build

Error logs / results

..../index.rst:line: Warning: toctree contains reference to document 'test' that doesn't have a title: no link will be generated

Expected results

I expected a more functional first steps instruction.

Environment info

• OS: ubuntu 16.04
• Python version:3.5
• Sphinx version:1.6.5

[tk0miya]

Yes, the tutorial is writtern for users who knows reST already. Indeed, it is not kindful for new comers.
+1 for updating!

[BMaxV]

Hey,

I'd like to give this issue a bump, I hope comments do that, since it's literally the bit that stops me from documenting a module I made. It's blocking my progress.

I have setup a readthedocs page with sphinx and it's not working because I can't get it to work because of this problem. Please help!

[jfbu]

To add a title you need some mark-up of the type

==============
 Présentation
==============

is this what you need? This is issue-tracker of Sphinx. For help, please use the http://groups.google.com/group/sphinx-users

there is gmane access gmane.comp.python.sphinx.user you can configure your newsreader to use news://news.gmane.org:119/gmane.comp.python.sphinx.user

reST docs

[BMaxV]

No the issue is not with rst itself, it's with how the toctree works and how to put new pages into the toctree, which as far as I understood it, is how sphinx does things.

The information on how to do that is missing from the documentation.

Is there a separate issue tracker for the documentation?

[jfbu]

Test projects do not have to have a toctree. But usually your index.rst file will contain something like

.. toctree::
   :maxdepth: 2

   intro
   tutorial
   invocation
   rest
   markup/index
   domains
   builders
   config
   intl
   theming
   ....

If you use sphinx-quickstart, you have skeleton ready-made.

Then each foo.rst must have a title.

[jfbu]

which information precisely do you feel is lacking from http://www.sphinx-doc.org/en/stable/tutorial.html ? we are willing to improve if needed.

about your question about separate issue tracker for documentation, no there isn't. But you can ask questions on the sphinx-users or sphinx-devel groups. We welcome pull requests.

[BMaxV]

I have run sphinx quickstart, my project looks like this

docs
    source
        index.rst
        page1.rst
        page2.rst
    build
        ...

This is my index.rst 's toctree:

.. toctree::
    page1
    page2
   :maxdepth: 2
   :caption: Contents:modules

When I run sphinx-build -b html /source /build

It produces an output, but there is a warning that page1 and page2 don't exist and the resulting index.html does not link to them either.

I'm assuming I'm doing something wrong, but as far as I can see I did what the instructions say.

[jfbu]

You need to read a bit of reST docs but I feel the sphinx tutorial is already very good ...

For example options come before contents so you need

.. toctree::
   :maxdepth: 2
   :caption: Contents:modules

   page1
   page2

to start with. And page1.rst and page2.rst must have a reST title.

Attention to indentation, too.

In Emacs, there is an ReST mode you can type C-cC-= on a string to convert it into a title.

Side note: one adds "documents", not "pages", to the toctree.

[jfbu]

Does it work really with sphinx-build -b html /source /build ? (presumably you are on Windows, I don't know how it handles paths), I would use in your set-up sphinx-build -b html source build/html

Sphinx is multi-target, you can also do sphinx-build -b latex source build/latex then.

Usage of make html, make latexpdf is more convenient (it will create a common build/doctrees repertory rather than one .doctrees per build/target). You need the conf.py in source.

[BMaxV]

My documents have titles as far as I can tell. I'm on linux. There is a conf.py in the source, I forgot to mention it.

Attention to indentation, too.

Right. How much though. Does it all have to be same, does the actual number matter, are there special rules for options or not, are tabs or spaces ok, ...?

The tutorial produces output an empty index page, but it's not producing enough output for me to learn what works and what does not.

The rst docs aren't helping either. This first link in the user docs doesn't mention document titles at all for example.

And the sphinx-build doesn't tell me that the document is missing the title, it's telling me that the documents are missing entirely. Which is just not true, it just can't find them.

What would really help me, would be if the tutorial took an example project, and if it's just a simple hello world module, and if it would show the workflow from just having the module to producing working output with multiple files. Preferably, you could create a working example project, that I or other users could download and play around with and build on.

[BMaxV]

Actually let me do that, I'll go as far as I can from the tutorial alone and you could just clone the whole repo to see what's wrong.

[jfbu]

Regarding invocation of sphinx-build there is a -M option which is nice,

sphinx-build -M html source build
sphinx-build -M latex source build

then you have build/doctrees, build/html, build/latex.

On Mac or Linux, using directly make command is very convenient. make html latex epub.

If you created your project using sphinx-quickstart it is all set up for this.

As per sample documents, actually any project on github can be examined. For example Sphinx itself

Now, as I said we welcome PR for documentation enhancement. As per reST, the Sphinx reST tutorial gives lots of information.

[BMaxV]

I don't know why, but my sphinx-quickstart has not setup make instructions. I don't know which question I should have answered with "yes" for quickstart to setup a makefile, but the tutorial does not specify that either. Let me just write my example thing, I'll update when I've done that. Maybe then we can figure out what's missing from the tutorial and why my setup doesn't work.

[jfbu]

Hmm?

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: 
> Create Windows command file? (y/n) [y]: 

Creating file ./source/conf.py.
Creating file ./source/index.rst.
Creating file ./Makefile.
Creating file ./make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file ./source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

[BMaxV]

Ok nvm the makefile. Here is the example:

https://github.com/BMaxV/sphinx_tutorial_example

Now, what do I have to do to make sphinx automatically document my project and how do I add pages to the docs manually?

[jfbu]

diff --git a/new_project/docs/source/conf.py b/new_project/docs/source/conf.py
index e7a2a8e..423c077 100644
--- a/new_project/docs/source/conf.py
+++ b/new_project/docs/source/conf.py
@@ -17,9 +17,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../'))


 # -- General configuration ------------------------------------------------
@@ -103,7 +103,8 @@ html_static_path = ['_static']
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
 html_sidebars = {
     '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
+        'about.html',
+        'navigation.html',
         'searchbox.html',
     ]
 }
diff --git a/new_project/docs/source/hello_world_doc.rst b/new_project/docs/source/hello_world_doc.rst
new file mode 100644
index 0000000..739aaa5
--- /dev/null
+++ b/new_project/docs/source/hello_world_doc.rst
@@ -0,0 +1,8 @@
+======================================
+ Documentation for hello_world module
+======================================
+
+.. automodule:: hello_world
+   :members:
+   :imported-members:
+
diff --git a/new_project/docs/source/index.rst b/new_project/docs/source/index.rst
index 4c19989..645301f 100644
--- a/new_project/docs/source/index.rst
+++ b/new_project/docs/source/index.rst
@@ -10,7 +10,7 @@ Welcome to test's documentation!
    :maxdepth: 2
    :caption: Contents:

-
+   hello_world_doc

 Indices and tables
 ==================

Please refer to autodoc and to apidoc

This looks appropriate for your test project:

sphinx-apidoc -F -a -o docs raw_python/

then explore the created files, particularly conf.py.

[BMaxV]

Thank you, this is perfect.