Discussion:
[sphinx-users] sphinx-apidoc question
r***@gmail.com
2018-02-21 04:34:58 UTC
Permalink
I'm using sphinx for the first time for my first python package:
https://github.com/raybellwaves/cfanalytics

I was able to follow the readthedocs.org get started page
<https://docs.readthedocs.io/en/latest/getting_started.html>.

I'm now trying to document and show the API.

Whilst in the docs folder
I then tried:
sphinx-apidoc -o source/ ../cfanalytics
which now lists:

$ cd source
$ ls
cfanalytics.core.rst cfanalytics.rst cfanalytics.tests.rst modules.rst


But i'm now not sure what to do with these and how to include it my
index.rst to show something on http://cfanalytics.readthedocs.io/en/latest/#

Opening the file
https://github.com/raybellwaves/cfanalytics/blob/master/docs/_build/html/py-modindex.html seems
fine on my laptop. It may be something to do with readthedocs which i'm
looking into (
https://stackoverflow.com/questions/48878411/readthedocs-build-failing-using-aiohttp
)

I'm now not sure how to include these in any 'toctrees' (see build output)
below.

You can see my files
here: https://github.com/raybellwaves/cfanalytics/tree/master/docs

Cheers,
Ray

(cfa) UM-404XFVH4:docs Ray$ sphinx-autobuild . _build/html


+--------- manually triggered build
---------------------------------------------

| *Running Sphinx v1.6.6*

| *loading pickled environment... *done

| *building [mo]: *targets for 0 po files that are out of date

| *building [html]*: targets for 1 source files that are out of date

| *updating environment: *0 added, 1 changed, 0 removed

| *reading sources... *[100%] index

|

| *looking for now-outdated files... *none found

| *pickling environment... *done

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/source/cfanalytics.core.rst:
WARNING: document isn't included in any toctree

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/source/modules.rst:
WARNING: document isn't included in any toctree

| *checking consistency... *done

| *preparing documents... *done

| *writing output... *[100%] index

|

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/index.rst:7:
WARNING: toctree contains reference to document 'README' that doesn't have
a title: no link will be generated

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/index.rst:7:
WARNING: toctree contains reference to document 'README' that doesn't have
a title: no link will be generated

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/index.rst:7:
WARNING: toctree contains reference to document 'README' that doesn't have
a title: no link will be generated

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/index.rst:7:
WARNING: toctree contains reference to document 'README' that doesn't have
a title: no link will be generated

| *generating indices...* genindex py-modindex

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/index.rst:7:
WARNING: toctree contains reference to document 'README' that doesn't have
a title: no link will be generated

| *highlighting module code... *[ 33%] *cfanalytics.core.cfopendata*

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/index.rst:7:
WARNING: toctree contains reference to document 'README' that doesn't have
a title: no link will be generated

| *highlighting module code... *[ 66%] *cfanalytics.tests*

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/index.rst:7:
WARNING: toctree contains reference to document 'README' that doesn't have
a title: no link will be generated

| *highlighting module code... *[100%] *cfanalytics.tests.test_cfopendata*

|

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/index.rst:7:
WARNING: toctree contains reference to document 'README' that doesn't have
a title: no link will be generated

/Volumes/SAMSUNG/WORK/CFanalytics_2017/GitHub_folder/cfanalytics/docs/index.rst:7:
WARNING: toctree contains reference to document 'README' that doesn't have
a title: no link will be generated

| *writing additional pages...* search

| *copying static files... *done

| *copying extra files... *done

| *dumping search index in English (code: en) ... *done

| *dumping object inventory... *done

| *build succeeded, 11 warnings.*

+--------------------------------------------------------------------------------
--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+***@googlegroups.com.
To post to this group, send email to sphinx-***@googlegroups.com.
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.
shirou
2018-02-21 07:16:21 UTC
Permalink
Hi,

from your conf.py, your project not separete source and build directories.
So, you can output to exact same directory. (-o specified ".")

cd docs
sphinx-apidoc -o . ../cfanalytics
make html

works for me.

Also, it generates this warning.
cfanalytics/docs/index.rst:7: WARNING: toctree contains reference to
document 'README' that doesn't have a title: no link will be generated

To avoid this warning, just add title line to head of README.rst like this.

cfanalytics
--------------


thanks,
WAKAYAMA Shirou
Post by r***@gmail.com
https://github.com/raybellwaves/cfanalytics
I was able to follow the readthedocs.org get started page.
I'm now trying to document and show the API.
Whilst in the docs folder
sphinx-apidoc -o source/ ../cfanalytics
$ cd source
$ ls
cfanalytics.core.rst cfanalytics.rst cfanalytics.tests.rst modules.rst
But i'm now not sure what to do with these and how to include it my
index.rst to show something on http://cfanalytics.readthedocs.io/en/latest/#
Opening the file
https://github.com/raybellwaves/cfanalytics/blob/master/docs/_build/html/py-modindex.html
seems fine on my laptop. It may be something to do with readthedocs which
i'm looking into
(https://stackoverflow.com/questions/48878411/readthedocs-build-failing-using-aiohttp)
I'm now not sure how to include these in any 'toctrees' (see build output)
below.
https://github.com/raybellwaves/cfanalytics/tree/master/docs
Cheers,
Ray
(cfa) UM-404XFVH4:docs Ray$ sphinx-autobuild . _build/html
+--------- manually triggered build
---------------------------------------------
| Running Sphinx v1.6.6
| loading pickled environment... done
| building [mo]: targets for 0 po files that are out of date
| building [html]: targets for 1 source files that are out of date
| updating environment: 0 added, 1 changed, 0 removed
| reading sources... [100%] index
|
| looking for now-outdated files... none found
| pickling environment... done
WARNING: document isn't included in any toctree
WARNING: document isn't included in any toctree
| checking consistency... done
| preparing documents... done
| writing output... [100%] index
|
WARNING: toctree contains reference to document 'README' that doesn't have a
title: no link will be generated
WARNING: toctree contains reference to document 'README' that doesn't have a
title: no link will be generated
WARNING: toctree contains reference to document 'README' that doesn't have a
title: no link will be generated
WARNING: toctree contains reference to document 'README' that doesn't have a
title: no link will be generated
| generating indices... genindex py-modindex
WARNING: toctree contains reference to document 'README' that doesn't have a
title: no link will be generated
| highlighting module code... [ 33%] cfanalytics.core.cfopendata
WARNING: toctree contains reference to document 'README' that doesn't have a
title: no link will be generated
| highlighting module code... [ 66%] cfanalytics.tests
WARNING: toctree contains reference to document 'README' that doesn't have a
title: no link will be generated
| highlighting module code... [100%] cfanalytics.tests.test_cfopendata
|
WARNING: toctree contains reference to document 'README' that doesn't have a
title: no link will be generated
WARNING: toctree contains reference to document 'README' that doesn't have a
title: no link will be generated
| writing additional pages... search
| copying static files... done
| copying extra files... done
| dumping search index in English (code: en) ... done
| dumping object inventory... done
| build succeeded, 11 warnings.
+--------------------------------------------------------------------------------
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+***@googlegroups.com.
To post to this group, send email to sphinx-***@googlegroups.com.
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.
r***@gmail.com
2018-02-22 02:02:21 UTC
Permalink
Thanks for helping me learn sphinx!
Post by shirou
Hi,
from your conf.py, your project not separete source and build directories.
So, you can output to exact same directory. (-o specified ".")
cd docs
sphinx-apidoc -o . ../cfanalytics
make html
works for me.
Also, it generates this warning.
cfanalytics/docs/index.rst:7: WARNING: toctree contains reference to
document 'README' that doesn't have a title: no link will be generated
To avoid this warning, just add title line to head of README.rst like this.
cfanalytics
--------------
thanks,
WAKAYAMA Shirou
Post by r***@gmail.com
https://github.com/raybellwaves/cfanalytics
I was able to follow the readthedocs.org get started page.
I'm now trying to document and show the API.
Whilst in the docs folder
sphinx-apidoc -o source/ ../cfanalytics
$ cd source
$ ls
cfanalytics.core.rst cfanalytics.rst cfanalytics.tests.rst modules.rst
But i'm now not sure what to do with these and how to include it my
index.rst to show something on
http://cfanalytics.readthedocs.io/en/latest/#
Post by r***@gmail.com
Opening the file
https://github.com/raybellwaves/cfanalytics/blob/master/docs/_build/html/py-modindex.html
Post by r***@gmail.com
seems fine on my laptop. It may be something to do with readthedocs
which
Post by r***@gmail.com
i'm looking into
(
https://stackoverflow.com/questions/48878411/readthedocs-build-failing-using-aiohttp)
Post by r***@gmail.com
I'm now not sure how to include these in any 'toctrees' (see build
output)
Post by r***@gmail.com
below.
https://github.com/raybellwaves/cfanalytics/tree/master/docs
Cheers,
Ray
(cfa) UM-404XFVH4:docs Ray$ sphinx-autobuild . _build/html
+--------- manually triggered build
---------------------------------------------
| Running Sphinx v1.6.6
| loading pickled environment... done
| building [mo]: targets for 0 po files that are out of date
| building [html]: targets for 1 source files that are out of date
| updating environment: 0 added, 1 changed, 0 removed
| reading sources... [100%] index
|
| looking for now-outdated files... none found
| pickling environment... done
WARNING: document isn't included in any toctree
WARNING: document isn't included in any toctree
| checking consistency... done
| preparing documents... done
| writing output... [100%] index
|
WARNING: toctree contains reference to document 'README' that doesn't
have a
Post by r***@gmail.com
title: no link will be generated
WARNING: toctree contains reference to document 'README' that doesn't
have a
Post by r***@gmail.com
title: no link will be generated
WARNING: toctree contains reference to document 'README' that doesn't
have a
Post by r***@gmail.com
title: no link will be generated
WARNING: toctree contains reference to document 'README' that doesn't
have a
Post by r***@gmail.com
title: no link will be generated
| generating indices... genindex py-modindex
WARNING: toctree contains reference to document 'README' that doesn't
have a
Post by r***@gmail.com
title: no link will be generated
| highlighting module code... [ 33%] cfanalytics.core.cfopendata
WARNING: toctree contains reference to document 'README' that doesn't
have a
Post by r***@gmail.com
title: no link will be generated
| highlighting module code... [ 66%] cfanalytics.tests
WARNING: toctree contains reference to document 'README' that doesn't
have a
Post by r***@gmail.com
title: no link will be generated
| highlighting module code... [100%] cfanalytics.tests.test_cfopendata
|
WARNING: toctree contains reference to document 'README' that doesn't
have a
Post by r***@gmail.com
title: no link will be generated
WARNING: toctree contains reference to document 'README' that doesn't
have a
Post by r***@gmail.com
title: no link will be generated
| writing additional pages... search
| copying static files... done
| copying extra files... done
| dumping search index in English (code: en) ... done
| dumping object inventory... done
| build succeeded, 11 warnings.
+--------------------------------------------------------------------------------
Post by r***@gmail.com
--
You received this message because you are subscribed to the Google
Groups
Post by r***@gmail.com
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send
an
<javascript:>.
Post by r***@gmail.com
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+***@googlegroups.com.
To post to this group, send email to sphinx-***@googlegroups.com.
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.
Loading...