Nbdev and Gitlab (source links)

tom_500 · September 6, 2022, 7:28am

Hi,

first of all thanks for this great library, nbdev is a great tool.

I am using it with gitlab and so far it works great. I have set up the CI-pipeline to create the docs and publish them on gitlab pages – I am happy to share my experience If anyone is interested.

However, the only thing I am currently struggeling with are the source-links in the documentation. There is a very small difference between the urls that are created by nbdev and the urls working in gitlab:

nbdev: https://gitlab.com/<repo>/projects/<project>/blob/main/<code>/code.py`
gitlab: https://gitlab.com/<repo>/projects/<project>/-/blob/main/<project>/code.py`

so because of this difference (the additional /-/ in the link), the source links in the documentation are failing.

I think i have found the place in the nbdev source where the links are created.

github.com

fastai/nbdev/blob/5fac17443f62ae9a2d370c9f571fb3831340cb3b/nbdev/doclinks.py#L158


      
              return d
          
          
def _lineno(sym, fname): return _get_exps(fname).get(sym, None) if fname else None
          
          
# %% ../nbs/09_API/04b_doclinks.ipynb 24
          def _qual_sym(s, settings):
              if not isinstance(s,tuple): return s
              nb,py = s
              nbbase = urljoin(settings["doc_host"]+'/',settings["doc_baseurl"])
              nb = urljoin(nbbase+'/', nb)
              gh = urljoin(settings["git_url"]+'/', f'blob/{settings["branch"]}/{py}')
              return nb,py,gh
          
          
def _qual_mod(mod_d, settings): return {sym:_qual_sym(s, settings) for sym,s in mod_d.items()}
          def _qual_syms(entries):
              settings = entries['settings']
              if 'doc_host' not in settings: return entries
              return {'syms': {mod:_qual_mod(d, settings) for mod,d in entries['syms'].items()}, 'settings':settings}
          
          
# %% ../nbs/09_API/04b_doclinks.ipynb 25
          _re_backticks = re.compile(r'`([^`\s]+)`')

Does anyone have any ideas or suggestions on how to solve this problem? I thought about a small script changing the links in a post processing step, but maybe there is a better way?

Thanks

michaelaye · September 6, 2022, 9:01am

i have no solution to your problem, but i’m sure several people would be happy to read your experiences on using nbdev with gitlab in a blog post or here…

guillaumeramelet · September 6, 2022, 2:14pm

interested as well.
Have to use gitlab at work, and would like to publish to our artifactory using gitlab

pabloms92 · September 6, 2022, 3:26pm

Hi @tom_500 ,
The doclinks file is already importing the nbdev.config so one could access the host from the settings.ini with nbdev.config.get_config().

I don’t think it is the most elegant way, but probably this could work:

if get_config().get('host') == 'gitlab' :
    gh = urljoin( <gitlab-path>)
else:
    gh = urljoin( <github-path>)

pabloms92 · September 6, 2022, 3:36pm

I don’t know if I should open a new discussion for this, but did anybody here manage to deploy their project in gitlab pages ?
I don’t know if there is something that we should change in the .gitlab-cy.yml or it all comes from the nbdev_deploy script.

jeremy · September 7, 2022, 2:48am

Feel free to use this issue to add specific things that are needed to better support Gitlab:

tom_500 · September 7, 2022, 10:09am

Ok, maybe I find a nice solution will post it there, thanks

tom_500 · September 7, 2022, 10:11am

hi @pabloms92, @guillaumeramelet, @michaelaye I posted an example here, maybe this helps