FAQ

  1. Define a magic command
  2. Do I need to shutdown the kernel after running a notebook?
  3. How to activate the logs?
  4. How to build pyquickhelper with Jenkins?
  5. How to create a virtual environment?
  6. How to dd an extra layer to the documentation?
  7. How to generate auto_rss_server.py?
  8. How to get more about latex errors?
  9. How to hide command line window while compiling latex?
  10. How to merge notebook?
  11. How to run a local server which serves the documentation?
  12. List of Sphinx commands added by pyquickhelper
  13. Why a ¿ is showing the final PDF?
  14. Why doesn't the documentation show compiled submodules?
  15. Why module pylzma does not work?

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 temrinate until all kernels are shutdown.

(original entry : notebook_runner.py:docstring of pyquickhelper.ipythonhelper.notebook_runner.NotebookRunner, line 14)

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, :epkg:`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 41)

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 17)

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 122)

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_latex

if 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 : sphinxm_convert_doc_helper.py:docstring of pyquickhelper.helpgen.sphinxm_convert_doc_helper.rst2html, line 103)

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 compile. 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 : sphinxm_convert_doc_helper.py:docstring of pyquickhelper.helpgen.sphinxm_convert_doc_helper.rst2html, line 127)

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.serverdoc.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.serverdoc.documentation_server.run_doc_server, line 12)

List of Sphinx commands added by pyquickhelper

  • bigger: to write with a custom size
  • blocref: to add a definition (or any kind of definition)
  • blocreflist: to list all definitions
  • blogpost: to add a blog post, this command does not behave like the others, it should only be used in folder _doc/sphinxdoc/source/blog
  • blogpostagg: to aggregate blog post, this should be manually added, the module pyquickhelper is preprocessing the documentation to produce pages containing such commands
  • cmdref: to documentation a script the module makes available on the command line
  • cmdreflist: to list all commands
  • epkg: avoid repeating the same references in many places
  • exref: to add an example
  • exreflist: to list all example
  • faqref: to add a FAQ
  • faqreflist: to list all FAQ
  • mathdef: to add a mathematical definition (or any kind of definition)
  • mathdeflist: to list all definitions
  • nbref: to add a magic command
  • nbreflist: to list all magic commands
  • runpython: to run a script and display the output, it can be used to generate documentation
  • sharenet: to add buttons to share the page on a socal network
  • todoext: to add an issue or a work item
  • todoextlist: to list all issues or work item

These commands are documented in Sphinx Extensions.

(original entry : contribute.rst, line 381)

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 implemeted, the unicode will unfortunately be removed in this function.

(original entry : post_process.py:docstring of pyquickhelper.helpgen.post_process.post_process_latex, line 24)

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)