I would like to offer my JupyterLab notebooks in several languages (de-de, en-us).
In order to do so, I marked some strings
import gettext
domain = 'my_application_name'
localedir = '.'
translate = gettext.translation(domain, localedir, fallback=True)
_ = translate.gettext # using _ as name for the translation function is kind of standard in python
# do not confuse with private markers or underscore library
# https://github.com/serkanyersen/underscore.py
print(_('Hello World'))
print(_('another translation key'))
Then I downloaded xgettext.exe for windows from
https://github.com/mlocati/gettext-iconv-windows/releases/download/v0.21-v1.16/gettext0.21-iconv1.16-static-64.zip
and tried to extract the strings with following console command:
xgettext.exe my_notebook.ipynb
I got the warning
xgettext.exe: warning: file 'my_notebook.ipynb' extension 'ipynb' is unknown; will try C
and no output file was generated.
=> What is the recommented way for extracting translatable strings from JupyterLab notebooks?
I would prefer a solution, where no extra binary (like xgettext.exe) would be required on windows.
Does JupyterLab itself provide some translation features/extension (not for the UI but for notebooks)?
As a possible workaround, the notebook could first be converted to a python file with nbconvert and then passed to xgettext.exe. However, that seems to be too complicated. There should be a more elegant solution.
(The extraction of translatable strings from python files does work on windows, e.g.
xgettext.exe my_python_file.py
)
The rough workflow for translations seems to be:
Mark all strings that should be translated
Generate a translation file template from the strings (="master list" or Portable Object Template (POT) file)
Translate the translation file template
Apply the translation file
Related:
https://github.com/jupyterlab/jupyterlab/issues/11753
https://docs.python.org/3/library/i18n.html
https://www.mattlayman.com/blog/2015/i18n/
Here is the already mentioned workaround based on nbconvert and xgettext:
jupyter nbconvert --to script my_notebook.ipynb --output z_temp_file_for_translation
xgettext.exe z_temp_file_for_translation.py -o translations.pot
del z_temp_file_for_translation.py
As an alternative to xgettext, the python package Babel can be used:
pip install Babel
Also see: http://babel.pocoo.org/en/latest/cmdline.html#extract
jupyter nbconvert --to script my_notebook.ipynb --output z_temp_file_for_translation
pybabel extract z_temp_file_for_translation.py -o translations.pot
del z_temp_file_for_translation.py
I have my sphinx documentation set up and want to use a custom theme. I have read the theme instructions on the sphinx website: http://www.sphinx-doc.org/en/stable/theming.html, but it doesn't work.
I have my theme name the same as it is in the conf.py file and it is in a zip folder in the same directory, but i keep getting the following error:
Theme error:
no theme named 'tera' found (missing theme.conf?)
make: *** [html] Error 2
My conf.py code is:
html_theme = "tera"
html_theme_options = {
}
html_theme_path = ['.']
As per the instructions, I have got a theme.conf file in the .zip file along with everything else I need. Not sure how to fix.
In my theme.conf file I have:
[theme]
inherit = basic
stylesheet = css/Terra.css
pygments_style = default
File structure is as follows: Documents > Documentation >_themes. Inside themes I have a 'tera' folder and a 'tera.zip' file.
I've also tried just putting the tera.zip file in my documentation folder directly, so its in the same directory as the conf.py file and still no luck
I currently had the same problem. My issue was that zip creates by default a directory inside the zip file, thus theme.conf is not in its root.
Doing
$ zip -r tera.zip tera/*
gives the following:
$ less tera.zip
... Name
... ----
... tera/theme.conf
where I truncated the uninteresting output (...). If you do however
$ cd tera
$ zip -r tera.zip *
the configuration file will be at the root and sphinx works.
I have a cmake file from which i am executing a python script using "execute_command" as follows:
execute_process (COMMAND C:/Programs/Python27/python.exe "C:/packaging/doc/release_doc.py"
--var_ProjectName "${TARGET}"
--var_version "${_VERSION}" OUTPUT_FILE "C:/packaging/doc/")
When the cmake is executed i am not getting the output at the location specified inside "OUTPUT_FILE". The python file which i am executing is actually compiling a latex .tex file and hence generating a the corresponding pdf document along with the .log file, .aux file and .out file.
When i execute the python script from the location where the latex .tex document is located i get all the files generated at the same location and pdf is all alligned but when i have to execute the same python script from the cmake i am getting all the four files placed at the location different from .tex document and the pdf file alignment gets distrupted.
So, please suggest how can i have the this python file executed from within the cmake and the output of files at the location as i desire.
Is "C:/packaging/doc/" a folder? Then please replace it by something like "C:/packaging/doc/output.txt".
you can also try using OUTPUT_VARIABLE and check if it makes any difference:
execute_process (COMMAND COMMAND C:/Programs/Python27/python.exe "C:/packaging/doc/release_doc.py" --var_ProjectName "${TARGET}" --var_version "${_VERSION}" OUTPUT_VARIABLE test)
message(${test})
file(WRITE "C:/packaging/doc/output2.txt" "${test}")
I'm trying to create a HTML report using pyreport and it works up to the single point, that the LaTeX formulae are not generated.
Here is the input file I use for testing:
#$ This is \LaTeX : $c = 2\cdot(a+b)$
Than I run pyreport -l -t html --verbose file.py, but the report that I get is empty. When I add other comments to the input file, or some Python code, than it is displayed properly within the report. Here is the output from pyreport:
Running python script
/tmp/file.py:
Outputing report to
/tmp/file.html Ran script in 0.13s
I'm using Ubuntu and I have the texlive package installed. Why isn't the formula added to the report?
I think i have find the problem.
The problem is the RST tools to convert in html.
In pyreport, when you choose the math mode, the program will do the sentence in a bock .. raw:: LaTeX
But in the new version of rst2html, this command doesnt work, it's replace by:
.. math::
If you use the command:
pyreport -l -e -t rst --verbose file.py
and after
rst2html file.rst > test.html
You will see the problem.
You can change that in pyreport code, in main.py of pyreport. (use a locate to find it). And replace the
.. raw:: Latex
, by
.. math::
The last problem is for the command \LaTeX, that's not in a math mode of latex. So it's not work.
You can report to RST documentation http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw
I have a project hosted on GitHub. For this I have written my README using the Markdown syntax in order to have it nicely formatted on GitHub.
As my project is in Python I also plan to upload it to PyPi. The syntax used for READMEs on PyPi is reStructuredText.
I would like to avoid having to handle two READMEs containing roughly the same content; so I searched for a markdown to RST (or the other way around) translator, but couldn't find any.
The other solution I see is to perform a markdown/HTML and then a HTML/RST translation. I found some ressources for this here and here so I guess it should be possible.
Would you have any idea that could fit better with what I want to do?
I would recommend Pandoc, the "swiss-army knife for converting files from one markup format into another" (check out the diagram of supported conversions at the bottom of the page, it is quite impressive). Pandoc allows markdown to reStructuredText translation directly. There is also an online editor here which lets you try it out, so you could simply use the online editor to convert your README files.
As #Chris suggested, you can use Pandoc to convert Markdown to RST. This can be simply automated using pypandoc module and some magic in setup.py:
from setuptools import setup
try:
from pypandoc import convert
read_md = lambda f: convert(f, 'rst')
except ImportError:
print("warning: pypandoc module not found, could not convert Markdown to RST")
read_md = lambda f: open(f, 'r').read()
setup(
# name, version, ...
long_description=read_md('README.md'),
install_requires=[]
)
This will automatically convert README.md to RST for the long description using on PyPi. When pypandoc is not available, then it just reads README.md without the conversion – to not force others to install pypandoc when they wanna just build the module, not upload to PyPi.
So you can write in Markdown as usual and don’t care about RST mess anymore. ;)
2019 Update
The PyPI Warehouse now supports rendering Markdown as well! You just need to update your package configuration and add the long_description_content_type='text/markdown' to it. e.g.:
setup(
name='an_example_package',
# other arguments omitted
long_description=long_description,
long_description_content_type='text/markdown'
)
Therefore, there is no need to keep the README in two formats any longer.
You can find more information about it in the documentation.
Old answer:
The Markup library used by GitHub supports reStructuredText. This means you can write a README.rst file.
They even support syntax specific color highlighting using the code and code-block directives (Example)
PyPI now supports Markdown for long descriptions!
In setup.py, set long_description to a Markdown string, add long_description_content_type="text/markdown" and make sure you're using recent tooling (setuptools 38.6.0+, twine 1.11+).
See Dustin Ingram's blog post for more details.
You might also be interested in the fact that it is possible to write in a common subset so that your document comes out the same way when rendered as markdown or rendered as reStructuredText: https://gist.github.com/dupuy/1855764 ☺
For my requirements I didn't want to install Pandoc in my computer. I used docverter. Docverter is a document conversion server with an HTTP interface using Pandoc for this.
import requests
r = requests.post(url='http://c.docverter.com/convert',
data={'to':'rst','from':'markdown'},
files={'input_files[]':open('README.md','rb')})
if r.ok:
print r.content
I ran into this problem and solved it with the two following bash scripts.
Note that I have LaTeX bundled into my Markdown.
#!/usr/bin/env bash
if [ $# -lt 1 ]; then
echo "$0 file.md"
exit;
fi
filename=$(basename "$1")
extension="${filename##*.}"
filename="${filename%.*}"
if [ "$extension" = "md" ]; then
rst=".rst"
pandoc $1 -o $filename$rst
fi
Its also useful to convert to html. md2html:
#!/usr/bin/env bash
if [ $# -lt 1 ]; then
echo "$0 file.md <style.css>"
exit;
fi
filename=$(basename "$1")
extension="${filename##*.}"
filename="${filename%.*}"
if [ "$extension" = "md" ]; then
html=".html"
if [ -z $2 ]; then
# if no css
pandoc -s -S --mathjax --highlight-style pygments $1 -o $filename$html
else
pandoc -s -S --mathjax --highlight-style pygments -c $2 $1 -o $filename$html
fi
fi
I hope that helps
Using the pandoc tool suggested by others I created a md2rst utility to create the rst files. Even though this solution means you have both an md and an rst it seemed to be the least invasive and would allow for whatever future markdown support is added. I prefer it over altering setup.py and maybe you would as well:
#!/usr/bin/env python
'''
Recursively and destructively creates a .rst file for all Markdown
files in the target directory and below.
Created to deal with PyPa without changing anything in setup based on
the idea that getting proper Markdown support later is worth waiting
for rather than forcing a pandoc dependency in sample packages and such.
Vote for
(https://bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes)
'''
import sys, os, re
markdown_sufs = ('.md','.markdown','.mkd')
markdown_regx = '\.(md|markdown|mkd)$'
target = '.'
if len(sys.argv) >= 2: target = sys.argv[1]
md_files = []
for root, dirnames, filenames in os.walk(target):
for name in filenames:
if name.endswith(markdown_sufs):
md_files.append(os.path.join(root, name))
for md in md_files:
bare = re.sub(markdown_regx,'',md)
cmd='pandoc --from=markdown --to=rst "{}" -o "{}.rst"'
print(cmd.format(md,bare))
os.system(cmd.format(md,bare))