Hello,
I wanted to have info on how to use nbdev with other git repos (gitlab, or tuleap).
Also, when I open the docs/index file, I don’t see the same webpage as when I use serve docs, how can I host my doc elsewhere than github pages.
Thanks!
Other git repos have not been tested, so I don’t know how the hooks/CI should be adapted for those.
For hosting the doc elsewhere, you can redirect the docs (all our repos are on a .fast.ai address for instance). It implies some file CNAME in the docs folder (see here for an example in nbdev) and adding doc_host to the same value in settings.ini. There may be an option to switch in github as well, but I don’t remember it.
Merci Sylvain,
But if I just want to look at the doc on my browser (without doing serve)?
I don’t know how to do that no, and in my case, the local serve has the same output as the doc website.
Read the jekyll docs to learn how to do this - but basically, run bundle exec jekyll build then look in the _site folder it creates.
Thanks @jeremy, I will test with our git repo (tuleap) and post back.
I wanted to have info on how to use nbdev with other git repos (gitlab, or tuleap). Also, when I open the docs/index file.
Mybkexperience
I have seen similar issues when building the site with github and hosting on netlify. I don’t use any CNAME. I do a setup on netlify to pull /docs folder on each push. When building locally, I can get some rendering to work ( although theme is messed up ) but links in sidebar on local site don’t work at all. They still try to go to netlify links which is not available locally
This is my settings.ini which works on netlify , but causes issues when building locally
doc_host = https://<name>.netlify.com
doc_baseurl = %(doc_host)s/
git_url = https://github.com/%(user)s/%(lib_name)s/tree/%(branch)s/
Due to commercial constraints, we are usually not allowed to put complete source code in open . An ideal setup for me while building a package using nbdev in our office setting would be
-
Build it in 2 branches on a private git repository [ public , master]
-
Expose public branch using a netlify or similar hosting site. This can expose api, documentation and tutorials (all built using jupyter notebook) for using the package to public [or our customers]
-
Build a more private branch locally with more notebooks which use the same package but on our internal datasets which can’t be shared outside.
-
Eventually convince the company to release some of the source code publicly through some licensing mechanism
We use azure devop and gitlab for our internal developments. Along with this answer, I would appreciate some feedback on handling such use cases from the team.
Note: I realize I am asking 2 questions which is not recommended as per forum guidelines . If it’s unsuitable for the discussion here. I will create a separate topic on forum upon feedback
I have a problem similar to yours. I am developing with nbdev for our internal git server, that’s not problem, the githooks work., but I want to store the doc as a static website that one can browse locally after a gitclone. So you would go and look at the documentation on your clone repo, opening manually the index.html on your browser. I am not very good with html and how a website works, but I would expect this to be possible,
I tried putting
doc_host = .
doc_baseurl = .
and now I get a proper render with the template of the front page (the index) but links are broken. I will dig on this tomorrow.
Some trials and errors with settings.ini and now I can build docs locally on windows 10 and on netlify. Here is my settings.ini modifications:
url = https://<name>.netlify.com
doc_host = %(url)s
doc_baseurl =
Any other doc_baseurl like =’/’, ‘//’ will not work
2 Likes
Dumb question but how do we explore the docs locally after doing bundle exec jekyll build ?
I can see the contents in _site folder. When I open the index.html, it show exactly what is shown on github. However, When I click on other link, it shows file not found. The URL is file:///nbdev_template//my_module . I copy all files in _site to nbdev_template but it does not work either.
[Update]: I copy all the nbdev_template folder to / and it works. However now I need to click to index.html to force it redirect to the real page.
I’m using it on gitlab without any issues!
2 Likes
Easiest is to use bundle exec jekyll serve
1 Like
or type make docs_serve
2 Likes
Thanks for your help. I’m now encounter an error of import using nbdev. Can we remove the dot at the beginning of package ? For example I have this in the notebook
from mypackage.submodule import Submodule
using nbdev_buildlib convert it to .py as below:
from .submodule import Submodule
Can I change it to from submodule import Submodule
It is from an existing project I’m working on and the dot create error of relative import. Thanks
No, this is what makes nbdev build packages, which need relative imports. You most probably don’t have an __init__.py file in your mypackage folder if you get this error, so just create an empty one.
1 Like
I’m getting ‘no kernel named python3’ error when running nbdev_test_nbs in both fastcore and fastai2. Also, I get an “AssertionError: 'Use ‘create_config’ to create settings.ini for the first time” when running nbdev_nb2md in a fast_template.
Are the two errors related? I’ve tried uninstalling and re-installing nbdev, fastcore, and fastai2. I’ve tried different environments. I tried running create_config, updating conda. No luck.
nbdev_test_nbs error:
Error in /home/travis/git/fastcore/nbs/04_transform.ipynb:
No such kernel named python3
Traceback (most recent call last):
File "/home/travis/.local/bin/nbdev_test_nbs", line 11, in <module>
load_entry_point('nbdev', 'console_scripts', 'nbdev_test_nbs')()
File "/home/travis/.local/lib/python3.6/site-packages/fastscript/core.py", line 73, in _f
func(**args.__dict__)
File "/home/travis/git/nbdev/nbdev/cli.py", line 70, in nbdev_test_nbs
raise Exception(msg + '\n'.join([f.name for p,f in zip(passed,files) if not p]))
Exception: The following notebooks failed:
00_test.ipynb
01_foundation.ipynb
02_utils.ipynb
03_dispatch.ipynb
04_transform.ipynb
index.ipynb
nbdev_nb2md error:
File "/home/travis/git/nbdev/nbdev/export2html.py", line 101, in add_jekyll_notes
styles = Config().get('jekyll_styles', 'note,warning,tip,important').split(',')
File "/home/travis/git/nbdev/nbdev/imports.py", line 42, in __init__
assert self.config_file.exists(), "Use `create_config` to create settings.ini for the first time"
AssertionError: Use `create_config` to create settings.ini for the first time
Solved this issue. See this thread.
Can you give more info on how to setup for building the documentation?
I was using nbdev with pypi and noticed the plots/images cannot be seen in pypi web (You can check https://pypi.org/project/nbdev/ to see the issue). I modified the setup.py to fix this with the following code and was curious to know if I should open a PR for this:
readme_content = open('README.md').read()
# 
for ext in ['png', 'svg']:
#referencing the raw image from github, code from: 03_export2html.ipynb
readme_content = re.sub(r'!\['+ext+'\]\((.*)\)', '+'/'+cfg['branch']+'/\\1)', readme_content)
setuptools.setup(
name = cfg['lib_name'],
license = lic[0],
classifiers = [
'Development Status :: ' + statuses[int(cfg['status'])],
'Intended Audience :: ' + cfg['audience'].title(),
'License :: ' + lic[1],
'Natural Language :: ' + cfg['language'].title(),
] + ['Programming Language :: Python :: '+o for o in py_versions[py_versions.index(min_python):]],
url = 'https://github.com/{}/{}'.format(cfg['user'],cfg['lib_name']),
packages = setuptools.find_packages(),
include_package_data = True,
install_requires = requirements,
python_requires = '>=' + cfg['min_python'],
long_description = readme_content,
long_description_content_type = 'text/markdown',
zip_safe = False,
entry_points = { 'console_scripts': cfg.get('console_scripts','').split() },
**setup_cfg)