When I run sphinx-apidoc and then make html it produces doc pages that have "Subpackages" and "Submodules" sections and "module" and "package" at the end of each module/package name in the table of contents (TOC). How might I prevent these extra titles from being written without editing the Sphinx source?
here's an example doc pages I would like to make (notice TOC):
http://selenium.googlecode.com/svn/trunk/docs/api/py/index.html#documentation
I understand it is due to the apidoc.py file in the sphinx source (line 88):
https://bitbucket.org/birkenfeld/sphinx/src/ef3092d458cc00c4b74dd342ea05ba1059a5da70/sphinx/apidoc.py?at=default
I could manually edit each individual .rst file to delete these titles or just remove those lines of code from the script but then I'd have to compile the Sphinx source code. Is there an automatic way of doing this without manually editing the Sphinx source?
I was struggling with this myself when I found this question... The answers given didn't quite do what I wanted so I vowed to come back when I figured it out. :)
In order to remove 'package' and 'module' from the auto-generated headings and have docs that are truly automatic, you need to make changes in several places so bear with me.
First, you need to handle your sphinx-apidoc options. What I use is:
sphinx-apidoc -fMeET ../yourpackage -o api
Assuming you are running this from inside the docs directory, this will source yourpackage for documentation and put the resulting files at docs/api. The options I'm using here will overwrite existing files, put module docs before submodule docs, put documentation for each module on its own page, abstain from creating module/package headings if your docstrings already have them, and it won't create a table of contents file.
That's a lot of options to remember, so I just add this to the end of my Makefile:
buildapi:
sphinx-apidoc -fMeET ../yourpackage -o api
#echo "Auto-generation of API documentation finished. " \
"The generated files are in 'api/'"
With this in place, you can just run make buildapi to build your docs.
Next, create an api.rst file at the root of your docs with the following contents:
API Documentation
=================
Information on specific functions, classes, and methods.
.. toctree::
:glob:
api/*
This will create a table of contents with everything in the api folder.
Unfortunately, sphinx-apidoc will still generate a yourpackage.rst file with an ugly 'yourpackage package' heading, so we need one final piece of configuration. In your conf.py file, find the exclude_patterns option and add this file to the list. It should look something like this:
exclude_patterns = ['_build', 'api/yourpackage.rst']
Now your documentation should look exactly like you designed it in the module docstrings, and you never have to worry about your Sphinx docs and your in-code documentation being out of sync!
It's probably late, but the options maxdepth or titlesonly should do the trick.
More details :
http://sphinx-doc.org/latest/markup/toctree.html
The answer by Jen Garcia helped a lot but it requires to put repeat package names in docstrings. I used a Perl one-liner to remove the "module" or "package" suffix in my Makefile:
docs:
rm -rf docs/api docs/_build
sphinx-apidoc -MeT -o docs/api wdmapper
for f in docs/api/*.rst; do\
perl -pi -e 's/(module|package)$$// if $$. == 1' $$f ;\
done
$(MAKE) -C docs html
I didn't want to use the titles within my docstrings as I was following numpy style guidelines. So I first generate the rst files and then run the following python script as a post-processing step.
from pathlib import Path
src_dir = Path("source/api")
for file in src_dir.iterdir():
print("Processed RST file:", file)
with open(file, "r") as f:
lines = f.read()
junk_strs = ["Submodules\n----------", "Subpackages\n-----------"]
for junk in junk_strs:
lines = lines.replace(junk, "")
lines = lines.replace(" module\n=", "\n")
with open(file, "w") as f:
f.write(lines)
This script is kept in the same directory as the makefile. I also add the following lines to the makefile.
html:
# rm -r "$(BUILDDIR)"
python rst_process.py
#$(SPHINXBUILD) -M $# "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Now running make html builds the documentation in the way I want.
I'm not sure I'm 100% answering your question, but I had a similar experience and I realized I was running sphinx-apidoc with the -f flag each time, which created the .rst files fresh each time.
Now I'm allowing sphinx-apidoc to generate the .rst files once, but not overwriting them, so I can modify them to change titles/etc. and then run make html to propagate the changes. If I want to freshly generate .rst files I can just remove the files I want to regenerate or pass the -f flag in.
So you do have to change the rst files but only once.
In newer versions of Apidoc, you can use a custom Jinja template to control the generated output.
The default templates are here: https://github.com/sphinx-doc/sphinx/tree/5.x/sphinx/templates/apidoc
You can make a local copy of each template using the same names (e.g. source/_templates/toc.rst_t) and invoke sphinx-apidoc with the --templatedir option (e.g. sphinx-apidoc --templatedir source/_templates).
Once you are using your own template file, you can customize it however you want. For example, you can remove the ugly "package" and "module" suffix, which is added at this stage.
Related
I have a script that pulls in data from a server drive where I do not have the ability to alter the directory names and they all have spaces in them. I am using a Makefile to run the script (in Windows) and it is presenting a problem.
My initial workaround is having a python script run before make is called to copy the data from the server into my local folder, and it looks like this:
# grab_data.py
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("-o", "--output", help="output filepath")
args = parser.parse_args()
output_path = Path(args.output)
src = 'S:/Server Path/To Data I Need/File I Need.xlsx'
dst = output_path
shutil.copyfile(src, dst)
And I run my Makefile like this:
.PHONY : runall
runall : data/file_i_need.xlsx final_output.csv
python grab_data.py - o data/file_i_need.xlsx
final_output.csv : data/file_i_need.xlsx processing_script.py
python processing_script.py -i $< -o $#
I want to find some way to include the file 'S:/Server Path/To Data I Need/File I Need.xlsx' directly in the Makefile but cannot figure out what will work. Is there some other workaround that would allow me to do this?
Not sure what version of make you're using, but with gmake (which likely is one of the options around Windows) escaping spaces would work:
x\ yz: ab\ c
cp "$<" "$#"
Then you get:
$ make
cp "ab c" "x yz"
As pointed out in the comment, to not forgo it as too obvious. I've also double-quoted variables used in the recipe to make sure those are correctly passed through as a whole string. If a rule has multiple prerequisites and only one of them contains space(s), it's still the same story, you just need to make it the first prerequisite so that you can refer to "$<". If you had multiple prerequisites with spaces and wanted to refer to all of them, I fear you may be out of luck even trying to expand $^ with $(foreach ...) won't help.
I'm generating the docs of my python library with Sphinx. I use the extension sphinx.ext.viewcode
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.doctest",
"sphinx.ext.intersphinx",
"sphinx.ext.ifconfig",
"sphinx.ext.viewcode", # Add links to highlighted source code
"sphinx.ext.napoleon", # to render Google format docstrings
]
This generates a link to the source documentation, similarly to:
class MyClass(param1, param2)[source]
like in this image:
If I press source, I see the source code correctly in my HTML page.
I would like to do exactly the same when I generate a LaTeX file. I can't find in the documentation how to add the source code when you create a pdf from LaTeX. Any hint?
There is a way to add code to python through a package called listings. This package allows one to show code and even complete files.
For implementing this, in conf.py you can add:
latex_elements = {
"papersize": "letterpaper",
"pointsize": "10pt",
"figure_align": "htbp",
"preamble": r"""
\usepackage{listings}
\lstset{
language=Python, % the language of the code
title=\lstname % show the filename of files included with \lstinputlisting; also try caption instead of title
}
""",
}
there are more settings that can be added to lstset.
Then the code can be added in the .rst file as:
.. raw:: latex
\section{Code}
\lstinputlisting{../../../path/to/my/file.py}
According to the documentation for sphinx.ext.viewcode:
This extension works only on HTML related builders like html, applehelp, devhelp, htmlhelp, qthelp and so on except singlehtml.
.. seealso::
Class :class:`apps.business.models.Department`
Explanation goes here
`GNU tar manual, Basic Tar Format <http://link>`_
Documentation for tar archive files, including GNU tar extensions.
That creates a proper link to the class Department.
How do I change the HTML output to have a just a single class name, without 'apps.business.models' prefix?
so it reads Class Department in HTML?
There is the ~ (tilde) in standard cross-referencing syntax.
If you prefix the content with ~, the link text will only be the last component of the target. For example,
:py:meth:`~Queue.Queue.get`
will refer to Queue.Queue.get but only display get as the link text. This does not work with all cross-reference roles, but is domain specific.
There is also the directive .. currentmodule:: with some documentation and an example in another SO answer.
content/some_dir contains subdirectories that should not be scanned for pages or templates and .html files and images that should be presented as is. Including some_dir in STATIC_PATHS and PAGE_EXCLUDES doesn't seem to stop pelican from scanning through and warning me that my pages are formatted incorrectly, images don't have alt's, etc.
In my pelican site I have a LOT of pre-formatted static html that I didn't want to have to edit. (Static archive of old web forums - 30K html files)
You can use STATIC_PATHS, with ARTICLE_EXCLUDES and PAGE_EXCLUDES to do what you want, but you'll discover that for some reason pelican still wants to look at each file. Doing this increased my build times 10x or so with my data. In short, use the static_paths to add your html files, and then the excludes settings to tell pelican to not process them.
Instead I tried the following, and use this now. In my top-level directory, I made a directory 'output-skel' and then I edited my Makefile. In the html target, I added this line as one of the commands that is run:
rsync -SHqav output-skel/ $(OUTPUTDIR)
so my html make block looks like this:
html:
$(PELICAN) $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS)
rsync -SHqav output-skel/ $(OUTPUTDIR)
This way, I can put ANY file I want to include in my output in it's relative path in output-skel and have it show up where I want it.
This sure beats having 30k entries in my STATIC_PATHS. I put .htaccess files, static-html, some 'downloads' files there.
As an aside, I also add the following lines to my html make target:
chown -R root:www $(OUTPUTDIR)
find $(OUTPUTDIR) -type d | xargs chmod 750
find $(OUTPUTDIR) -type f | xargs chmod 640
Just to keep things neat and tidy.
You could try ARTICLE_EXCLUDES (list of directories to exclude when looking for articles) or IGNORE_FILES (list of file globbing patterns to match against the source files to be ignored by the processor).
Source : http://docs.getpelican.com/en/3.3.0/settings.html
We're evaluating Babel 0.9.5 [1] under Windows for use with Python 2.6 and have the following questions that we we've been unable to answer through reading the documentation or googling.
1) I would like to use an _ like abbreviation for ungettext. Is there a concencus on whether one should use n_ or N_ for this?
n_ does not appear to work. Babel does not extract text.
N_ appears to partially work. Babel extracts text like it does for gettext, but does not format for ngettext (missing plural argument and msgstr[ n ].)
2) Is there a way to set the initial msgstr fields like the following when creating a POT file?
I suspect there may be a way to do this via Babel cfg files, but I've been unable to find documentation on the Babel cfg file format.
"Project-Id-Version: PROJECT VERSION\n"
"Language-Team: en_US \n"
3) Is there a way to preserve 'obsolete' msgid/msgstr's in our PO files? When I use the Babel update command, newly created obsolete strings are marked with #~ prefixes, but existing obsolete message strings get deleted.
Thanks,
Malcolm
[1] http://babel.edgewall.org/
By default pybabel extract recognizes the following keywords: _, gettext, ngettext, ugettext, ungettext, dgettext, dngettext,N_. Use -k option to add others. N_ is often used for NULL-translations (also called deferred translations).
Update: The -k option can list arguments of function to be put in catalog. So, if you use n_ = ngettext try pybabel extract -k n_:1,2 ....
To answer question 2):
If you run Babel via pybabel extract, you can set Project-Id-Version via the --project and --version options.
If you run Babel via setup.py extract_messages, then Project-Id-Version is taken from the distribution (project name and version in the setup.py file).
Both ways also support the options --msgid-bugs-address and --copyright-holder for setting the POT metadata.