FAQ¶
Define a magic command
This class is an example of how a magic commands can be defined
with parameters as if it was a regular command in a terminal.
The class MagicClassExample
defines magic
command htmlhelp
and the associated parser.
Function load_ipython_extension
register the magic command through %load_ext pyquickhelper
.
The magic command can be unit tested with:
mg = MagicClassExample()
mg.add_context(context={"MagicClassExample": MagicClassExample})
cmd = "MagicClassExample -f text"
res = mg.htmlhelp(cmd)
assert "NB(example of a magic command)"
(original entry : magic_class_example.py:docstring of pyquickhelper.ipythonhelper.magic_class_example.MagicClassExample, line 1)
Do I need to shutdown the kernel after running a notebook?
If the class is instantiated with kernel=True, a kernel will be started. It must be shutdown otherwise the program might be waiting for it for ever. That is one of the reasons why the travis build does not complete. The build finished but cannot terminate until all kernels are shutdown.
(original entry : notebook_runner.py:docstring of pyquickhelper.ipythonhelper.notebook_runner.NotebookRunner, line 15)
How to activate the logs?
The following instruction will do:
fLOG(OutputPrint=True)
To log everything into a file:
fLOG(OutputPrint=True, LogFile="log_file.txt")
(original entry : flog.py:docstring of pyquickhelper.loghelper.flog.fLOG, line 24)
How to build pyquickhelper with Jenkins?
Jenkins is a task scheduler for continuous integration. You can easily schedule batch command to build and run unit tests for a specific project. To build pyquickhelper, you need to install python, pymyinstall, miktex, pandoc, sphinx.
Once Jenkins is installed, the command to schedule is:
set PATH=%PATH%;%USERPOFILE%\AppData\Local\Pandoc
build_setup_help_on_windows.bat
This works if you installed Jenkins with your credentials.
Otherwise, the path to pandoc.exe
needs to be changed.
And you can also read Schedule builds with Jenkins.
node.js might be required if a notebooks contain javascript.
(original entry : utils_tests.py:docstring of pyquickhelper.pycode.utils_tests.main_wrapper_tests, line 36)
How to create a virtual environment?
The following example creates a virtual environment. Packages can be added by specifying the parameter package.
from pyquickhelper.pycode import create_virtual_env
fold = "my_env"
if not os.path.exists(fold):
os.mkdir(fold)
create_virtual_env(fold)
(original entry : venv_helper.py:docstring of pyquickhelper.pycode.venv_helper.create_virtual_env, line 18)
How to dd an extra layer to the documentation?
The following commit on project python3_module_template shows which changes needs to be done to add an extra layer of for the documentation.
(original entry : sphinx_main.py:docstring of pyquickhelper.helpgen.sphinx_main.generate_help_sphinx, line 133)
How to generate auto_rss_server.py?
The following code generates the script auto_rss_local.py which runs a local server to read blog posts included in the documentation (it uses module pyrsslocal):
from pyquickhelper.pycode import write_module_scripts, __blog__
write_module_scripts(".", blog_list=__blog__, command="blog")
(original entry : setup_helper.py:docstring of pyquickhelper.pycode.setup_helper.write_module_scripts, line 18)
How to get more about latex errors?
Sphinx is not easy to use when it comes to debug latex expressions. I did not find an easy way to read the error returned by latex about a missing bracket or an unknown command. I finally added a short piece of code in
sphinx.ext.imgmath.py
just after the call to the executable indicated by imgmath_latexif b'...' in stdout or b'LaTeX Error' in stdout: print(self.builder.config.imgmath_latex_preamble) print(p.returncode) print("################") print(latex) print("..........") print(stdout.decode("ascii").replace("\r", "")) print("-----") print(stderr)It displays the output if an error happened.
(original entry : rst_converters.py:docstring of pyquickhelper.helpgen.rst_converters.rst2html, line 106)
How to hide command line window while compiling latex?
Sphinx calls latex through command line. On Windows, a command line window can annoyingly show up anytime a formula is compiled. The following can be added to hide it:
startupinfo = STARTUPINFO()
startupinfo.dwFlags |= STARTF_USESHOWWINDOW
And , startupinfo=startupinfo
must be added to lines p = Popen(...
.
(original entry : rst_converters.py:docstring of pyquickhelper.helpgen.rst_converters.rst2html, line 130)
How to merge notebook?
The following code merges two notebooks into the first one and stores the result unto a file.
from pyquickhelper.ipythonhelper import read_nb
nb1 = read_nb("<file1>", kernel=False)
nb2 = read_nb("<file2>", kernel=False)
nb1.merge_notebook(nb2)
nb1.to_json(outfile)
(original entry : notebook_runner.py:docstring of pyquickhelper.ipythonhelper.notebook_runner.NotebookRunner.merge_notebook, line 6)
How to run a local server which serves the documentation?
The following code will create a local server: http://localhost:8079/pyquickhelper/.
this_fold = os.path.dirname(pyquickhelper.server.documentation_server.__file__)
this_path = os.path.abspath( os.path.join( this_fold,
"..", "..", "..", "dist", "html") )
run_doc_server(None, mappings = { "pyquickhelper": this_path } )
The same server can serves more than one project. More than one mappings can be sent.
(original entry : documentation_server.py:docstring of pyquickhelper.server.documentation_server.run_doc_server, line 12)
List of Sphinx commands added by pyquickhelper
bigger
: to write with a custom sizeblocref
: to add a definition (or any kind of definition)blocreflist
: to list all definitionsblogpost
: to add a blog post, this command does not behave like the others, it should only be used in folder _doc/sphinxdoc/source/blogblogpostagg
: to aggregate blog post, this should be manually added, the module pyquickhelper is preprocessing the documentation to produce pages containing such commandscmdref
: to documentation a script the module makes available on the command linecmdreflist
: to list all commandsepkg
: avoid repeating the same references in many placesexref
: to add an exampleexreflist
: to list all examplefaqref
: to add a FAQfaqreflist
: to list all FAQmathdef
: to add a mathematical definition (or any kind of definition)mathdeflist
: to list all definitionsnbref
: to add a magic commandnbreflist
: to list all magic commandsrunpython
: to run a script and display the output, it can be used to generate documentationsharenet
: to add buttons to share the page on a socal networktodoext
: to add an issue or a work itemtodoextlist
: to list all issues or work item
These commands are documented in Sphinx Extensions.
(original entry : contribute.rst, line 373)
Why a ¿ is showing the final PDF?
Unicode, chinese characters are an issue because the latex compiler prompts on those if the necessary packages are not installed. pdflatex does not accepts inline chinese characters, xetex should be used instead: see How to input Traditional Chinese in pdfLaTeX. Until this is being implemented, the unicode will unfortunately be removed in this function.
(original entry : post_process.py:docstring of pyquickhelper.helpgen.post_process.post_process_latex, line 25)
Why doesn’t the documentation show compiled submodules?
The instruction .. automodule:: <name>
only shows objects obj
which verify obj.__module__ == name
. This is always the case
for modules written in Python but not necessarily for module
compiled from C language. When the module is declared,
the following structure contains the module name in second position.
This name must not be the submodule shortname but the name
the module has is the package. The C file
pyquickhelper/helpgen/compiled.c
implements submodule
pyquickhelper.helpgen.compiled
, this value must replace
<fullname>
in the structure below, not simply compiled.
static struct PyModuleDef moduledef = {
PyModuleDef_HEAD_INIT,
"<fullname>",
"Helper for parallelization with threads with C++.",
sizeof(struct module_state),
fonctions,
NULL,
threader_module_traverse,
threader_module_clear,
NULL
};
(original entry : utils_sphinx_doc.py:docstring of pyquickhelper.helpgen.utils_sphinx_doc.apply_modification_template, line 18)
Why module pylzma does not work?
The module pylzma
failed to decompress the file produced by the latest version
of 7z (2016-09-23). The compression
was changed by tweaking the command line. LZMA is used instead LZMA2.
The current version does not include this
commit.
Or you can clone the package
sdpython.pylzma
and build it yourself with python setup.py bdist_wheel
.
(original entry : compression_helper.py:docstring of pyquickhelper.filehelper.compression_helper.zip7_files, line 12)