21

I am quite new to sphinx and I am trying to use it as API reference for my project. Maybe after that as project documentation too.

I generate it using these two commands

sphinx-apidoc -e -o doc/api tracer
sphinx-build -b dirhtml doc/ build/doc/dirhtml

There is a problem that it produces this table of contents

- tracer package
    - tracer.lang package
        - tracer.lang.en module
    - tracer.packageManagers package
        - tracer.packageManagers.dnf module
        - tracer.packageManagers.dpkg module
        - tracer.packageManagers.portage module
        - ...
    - tracer.resources package
        - tracer.resources.ProcessesList module
        - tracer.resources.applications module
        - tracer.resources.args_parser module
        - ...

It is very unclear list cause of unnecessary redundant informations. It would be so much better this way:

- tracer package
    - lang package
        - en module
    - packageManagers package
        - dnf module
        - dpkg module
        - portage module
        - ...
    - resources package
        - ProcessesList module
        - applications module
        - args_parser module
        - ...

or maybe even better without package or module label on the end.

Anyway it doesn't look very well anywhere. For instance

class tracer.packageManagers.portage.Portage
    Bases: tracer.packageManagers.ipackageManager.IPackageManager

would be so much nicer as

class Portage
    Bases: IPackageManager

I know full names may be good on large project where module names can have same names, but I dont like it on my small project. Can I somehow tell apidoc to generate short names?

Can you please help me?

Thank you very much, FrostyX

FrostyX
  • 358
  • 3
  • 10
  • 8
    Does it work if you set `add_module_names = False` in conf.py? See http://sphinx-doc.org/config.html#confval-add_module_names – mzjn Aug 13 '14 at 10:29
  • Thank you, it actually helped a little bit. Now it looks like: `class Portage Bases: tracer.packageManagers.ipackageManager.IPackageManager` but on other places, there is a full names. – FrostyX Aug 13 '14 at 13:05

1 Answers1

16

As far as the table of contents goes, doing a search/replace in the source folder on all the *.rst files (after running sphinx-apidoc) is what finally worked for me.

search:

^(?:[a-zA-Z0-9]*[.])*([a-zA-Z0-9]+) (package|module)

replace:

\1 \2

...this shortens the title, which is what is displayed in the toctree. The only consequence is the title on that module's page will be the short name as well, but that didn't bother me since both the navigation and table of contents still make it clear what the parent package is.

As per the class/function names, mzjin's comment to the question:

set add_module_names = False in conf.py

should do the trick.

Ryan de Kleer
  • 1,246
  • 14
  • 24