Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[Mauro Carvalho Chehab <mchehab+samsung@kernel.org>]

Hi Daniel,

Em Wed, 19 Jun 2019 11:05:57 +0200
Daniel Vetter <daniel@ffwll.ch> escreveu:

> On Tue, Jun 18, 2019 at 10:55 PM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> > diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> > index fa30dfcfc3c8..b0f948d8733b 100644
> > --- a/Documentation/gpu/drm-mm.rst
> > +++ b/Documentation/gpu/drm-mm.rst
> > @@ -320,7 +320,7 @@ struct :c:type:`struct file_operations <file_operations>` get_unmapped_area
> >  field with a pointer on :c:func:`drm_gem_cma_get_unmapped_area`.
> >
> >  More detailed information about get_unmapped_area can be found in
> > -Documentation/nommu-mmap.rst
> > +Documentation/driver-api/nommu-mmap.rst  
> 
> Random drive-by comment: Could we convert these into hyperlinks within
> sphinx somehow, without making them less useful as raw file references
> (with vim I can just type 'gf' and it works, emacs probably the same).
> -Daniel

Short answer: I don't know how vim/emacs would recognize Sphinx tags.

There are two ways of doing hyperlinks to local files. The first one is to 
add a label at the other file and use a reference to such label, e. g. at
nommu-mmap.rst, you would add a label like:

	.. _drm_nommu-mmap:

at the beginning of the file.

Then, at drm-mm.rst, you would use :ref:`drm_nommu-mmap` (there are a
few other alternative tags that would work the same way).

The advantage is that you could move/rename documents anytime, without
needing to take care of it.

Perhaps it could be possible a tool like cscope to parse those in
order to provide such automation for Sphinx. I dunno.

-

The other way is to use:

	:doc:`nommu-mmap.rst` (if both files are at the same dir)

The :doc: path is the current directory. So, if a file at, let's say,
Documentation/gpu wants to refer another file at driver-api, it would
need to write it as:

	:doc:`../driver-api/nommu-mmap.rst`

I'm not sure if vim/emacs recognizes this syntax, though.

Perhaps this tag could be used as:

	:doc:`Documentation/driver-api/nommu-mmap.rst <../driver-api/nommu-map.rst`

But that looks too ugly to my taste.

-

On this conversion, I opted to not touch this. We may consider trying
to replace those 


Thanks,
Mauro