[PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
Mauro Carvalho Chehab
mchehab+samsung at kernel.org
Wed Jun 19 10:22:18 UTC 2019
Hi Daniel,
Em Wed, 19 Jun 2019 11:05:57 +0200
Daniel Vetter <daniel at ffwll.ch> escreveu:
> On Tue, Jun 18, 2019 at 10:55 PM Mauro Carvalho Chehab
> <mchehab+samsung at 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
More information about the dri-devel
mailing list