I have a python package and I am able to create sphinx documentation from the python code automatically with
sphinx-apidoc -f -o source --full path_to_package
make html
This works fine, and the html lists all submodules with their documentation.
But in the html I see the following sections/text:
Package name
Submodules
First module
docu...
Second module
docu ...
Each module does have its documentation, but how to place tom documentation text directly below the package name? I want to have the following structure:
Package name
General package documentation...
Submodules
First module
docu...
Second module
docu ...
How to generate a documentation to appear on the top-level of a sphinx-generated documentation, describing the whole package, by ONLY change code in the python package? I do not want to change/add/modify any of the files generated by sphinx.
Is this possible, and how to do that?
First put the documentation as a doc string in the packages __init__.py file.
Then look in the docs folder containing your .rst files.
Edit the .rst for the package - the one with the Module contents at the end.
Then cut the Module Contents section and paste it to be at the top, above subpackages.
Then run make html.
I realise that the op stated only changing python code in the original question, but given his later comment this does seem to be the answer.
Related
I'm trying to understand how to make Sphinx work.
I'm not Python developer - instead, I want to use reST and Sphinx for general purpose texts.
So, I have Python, DocUtils and Sphinx installed. I have test.rst inside C:\Test\ directory. Then, I launch cmd.exe in this directory and type: sphinx-quickstart. Then, I press Enter multiple times for default presets.
Then I have some new files in this folder, including make.bat. Then, I run: make.bat html. Then, the Sphinx HTML files are created. But when I open index.html - I don't see the contents of my original test.rst.
So, how to make it work?
(Despite the completely identical title, my question is not a duplicate of this in any sense).
You must add test to the toctree directive in your index.rst.
.. toctree::
:maxdepth: 2
test
See the documentation of Directives for additional options and syntax.
I am trying out Sphinx for generating documentation for a Python project. Just to make sure I can actually make it work, I have made a test project to try it out on: https://github.com/ThomasA/sphinxtest.
I have run sphinx-quickstart in the root of this repository. In the following questions, I specified 'doc' as the documentation root, named the project 'sphinxtest', entered 'Thomas Arildsen' as author, answered 'y' to the 'autodoc' option, and selected the default setting for everything else.
I expected the 'autodoc' option to cause the generation of a file 'amodule.rst' in the 'doc' folder. However, this does not get generated. I am puzzled by this. I thought this was what the 'autodoc' option was supposed to do and what I have seen examples of others apparently achieve with it. Sphinx completes without any error messages, so it seems to be doing what it thinks it should do. So, what could I be doing wrong?
I am using Sphinx v. 1.5.6 and Python 3.5.3, all installed with Anaconda.
autodoc does not generate the .rst source files.
Instead first use sphinx-apidoc to generate the source files. Then run Sphinx to make your documentation.
An alternative to Percy's answer is autoapi written by Carlos Jenkins. He provides a Sphinx extension that generates the ReST files per documentation generation. You can configure the output ReST by modifying a template file.
https://github.com/carlos-jenkins/autoapi
I am a rookie to the Python world, and now I find myself trying to learn how to properly create a Python package or module. I also have several requirements that must be met.
I have a core native DLL (we'll name it MyCore.dll) compiled from C++. This DLL must be deployed to a particular install location, as it's a core component of a product (we'll say ProgramFiles\MyProduct).
I have used SWIG to generate Python bindings for MyCore.dll. It has generated 2 files: _MyCoreBindings.pyd (essentially a DLL that references MyCore.dll) and MyCoreBindings.py (which loads _MyCoreBindings.pyd and provides a Python API to it).
Finally, I have a Python script (MyProduct.py) containing only an import, as my product must be imported in Python under the name MyProduct.SDK :
import MyCoreBindings as SDK
Thus, I want a user's Python script to be able to access it like so:
import MyProduct.SDK
File summary in order of dependency:
ProgramFiles\MyProduct\MyCore.dll
_MyCoreBindings.pyd
MyCoreBindings.py
MyProduct.py (I'm not sure I need this)
I've also read that the format of a Python package involves some directory structure mimicking the import path, and the possible inclusion of setup.py and __init__.py, but all materials I've read have not made it clear what must go in each of these files, and in what cases they are required. I am definitely not clear where this directory structure may be placed.
If you want Python to be able to import your module, then you have a couple of choices:
install the module to Python's site-packages folder.
modify the paths that Python searches for modules/packages to import. You can do that via a *.pth file or by modifying the path using Python's sys module (i.e. sys.path.append(/some/path) )
You use setup.py for installing your package and/or creating eggs/wheels etc. See the following for helpful hints:
https://docs.python.org/2/distutils/setupscript.html
https://pythonhosted.org/an_example_pypi_project/setuptools.html
You can create a package by using _init__.py inside a folder alongside your modules:
- MyProduct
- __init__.py
- MyCoreBindings.py
- _MyCoreBindings.pyd
The _init__.py file can be empty. This basically allows you to import the folder as MyProduct:
import MyProduct
MyProduct.MyCoreBindings
or
from MyProduct import MyCoreBindings as SDK
You won't need a MyProduct.py if you go with the __init__.py in the root folder. I hope that all made sense.
We don't want to be maintaining documentation as well as the source code, which is evolving rapidly at the moment, yet Sphinx seems to require a frustrating amount of setup and configuration. (We just need some basic API docs.) Is there not a single command you can run inside a python project that will just iterate over all of the packages, modules, classes and functions generating documentation as HTML?
The sphinx-apidoc splats stuff into a directory, and after modifying the conf.py to have our packages in the sys.path we can run "make html", but it only lists packages and modules without documenting any classes or functions.
Thanks!
The sphinx-apidoc tool will autogenerate stubs for your modules, which might be what you want.
Instructions
Make sure the autodoc module was enabled during Sphinx configuration.
extensions = ['sphinx.ext.autodoc']
within Sphinx's conf.py should do the trick.
Make sure conf.py adjusts sys.path accordingly (see the comments at lines 16-19 in the file).
sys.path.insert(0, os.path.abspath('/my/source/lives/here'))
Run sphinx-apidoc to generate skeletons.
sphinx-apidoc -o /my/docs/live/here /my/source/lives/here
Rebuild the docs. If all goes well, you shouldn't get the following sort of warning:
mymodule.rst:4: WARNING: autodoc can't import/find module 'mymodule'
Your module RSTs should now be populated.
I am using Eclipse for Python programming.
In my project, I have a file: main.py. This file is located in the root of the project files hierarchy. In the root itself, I created a folder with the name Classes in which I have a class file named: PositionWindow.py. This file contains a class PositionWindow and the class itself contains a function named: Center().
In main.py, I want to import this class [PositionWindow] and later call that function Center in the appropriate place.
I am not able to import that class correctly in main.py and not following how to call that function later.
You seem to be programming in java, still. I understand that you used java for a long time, but this is no longer java. This is python...
Python doesn't have directories. It has packages
Python doesn't have class files. It has modules.
You can have multiple classes in a module.
You can have multiple modules in a package.
I suggest you read at least the python basic tutorial (specially the part about packages and modules) so you can learn python, instead of trying to guess the language.
About the structure of your project, there's this article which is pretty good, and shows you how to do it.
shameless copy paste:
Filesystem structure of a Python project
by Jp Calderone
Do:
name the directory something related to your project. For example, if your
project is named "Twisted", name the
top-level directory for its source
files Twisted. When you do releases,
you should include a version number
suffix: Twisted-2.5.
create a directory Twisted/bin and put your executables there, if you
have any. Don't give them a .py
extension, even if they are Python
source files. Don't put any code in
them except an import of and call to a
main function defined somewhere else
in your projects.
If your project is expressable as a single Python source file, then put it
into the directory and name it
something related to your project. For
example, Twisted/twisted.py. If you
need multiple source files, create a
package instead (Twisted/twisted/,
with an empty
Twisted/twisted/__init__.py) and place
your source files in it. For example,
Twisted/twisted/internet.py.
put your unit tests in a sub-package of your package (note - this means
that the single Python source file
option above was a trick - you always
need at least one other file for your
unit tests). For example,
Twisted/twisted/test/. Of course, make
it a package with
Twisted/twisted/test/__init__.py.
Place tests in files like
Twisted/twisted/test/test_internet.py.
add Twisted/README and Twisted/setup.py to explain and
install your software, respectively,
if you're feeling nice.
Don't:
put your source in a directory called src or lib. This makes it hard
to run without installing.
put your tests outside of your Python package. This makes it hard to
run the tests against an installed
version.
create a package that only has a __init__.py and then put all your code into __init__.py. Just make a module
instead of a package, it's simpler.
try to come up with magical hacks to make Python able to import your module
or package without having the user add
the directory containing it to their
import path (either via PYTHONPATH or
some other mechanism). You will not
correctly handle all cases and users
will get angry at you when your
software doesn't work in their
environment.
Instead of creating "folder" in the root of your project, create a "package". Simply create a blank file called __init__.py and you should be able to import your module in main.py.
import Classes.PositionWindow
p = Classes.PositionWindow.PositionWindow()
p.Center()
However, you should read up on modules and packages, because your structure indicates that your approach may be flawed. First, a class doesn't have to be in a separate .py file like it does in Java. Further, your packages/modules/functions/methods should all be in lower case. Only class names should be in Upper case.
So you have this file layout:
/main.py
/Classes/PositionWindow.py (with Center inside it)
You have two choices:
Add "Classes" to your Python Path, allowing you to import PositionWindow.py directly.
Make "Classes" a package (possibly with a better name).
To add the Classes folder to your Python Path, set PYTHONPATH as an environment variable to include it. This works like your shell's PATH -- when you import PositionWindow, it will look through all the directories in your Python Path to find it.
Alternatively, if you add a blank file:
Classes/__init__.py
You can import the package and its contents like so in main.py:
import Classes.PositionWindow
x = Classes.PositionWindow.Center()