Hi Jani, I forget to mentioning, with a local copy of my kernel-doc script: https://github.com/return42/sphkerneldoc/blob/master/scripts/kernel-doc You could do reST markup in the source code comments and extract them. This might be a interim workaround which helps you not to edit source code comments twice. -- Markus-- Am 06.05.2016 um 13:23 schrieb Markus Heiser <markus.heiser@xxxxxxxxxxx>: > > Hy Jani, > > Am 04.05.2016 um 18:13 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > >>> Am 04.05.2016 um 17:09 schrieb Jonathan Corbet <corbet@xxxxxxx>: >>> >>>> I think all of this makes sense. It would be really nice to have the >>>> directives in the native sphinx language like that. I *don't* think we >>>> need to aim for that at the outset; the docproc approach works until we can >>>> properly get rid of it. What would be *really* nice would be to get >>>> support for the kernel-doc directive into the sphinx upstream. >>> >>> No need for kernel-doc directive in sphinx upstream, later it will be >>> an extension which could be installed by a simple command like >>> "pip install kernel-doc-extensions" or similar. >>> >>> I develop these required extension (and more) within my proof of concept >>> on github ... this takes time ... if I finished all my tests and all is >>> well, I will build the *kernel-doc-extensions* package and deploy it >>> on https://pypi.python.org/pypi from where everyone could install this >>> with "pip". >> >> I think we should go for vanilla sphinx at first, to make the setup step >> as easy as possible for everyone. Even if it means still doing that ugly >> docproc step to call kernel-doc. We can improve from there, and I >> definitely appreciate your work on making this work with sphinx >> extensions. > > +1 > >> That said, how would it work to include the kernel-doc extension in the >> kernel source tree? Having things just work if sphinx is installed is >> preferred over requiring installation of something extra from pypi. (I >> know this may sound backwards for a lot of projects, but for kernel I'm >> pretty sure this is how it should be done.) > > Thats all right. Lets talk about the extension infrastructure by example: > > First we have to chose a folder where we place all the *sphinx-documentation* > I recommending: > > /share/linux/Documentation/sphinx > > Next we have to chose a folder where reST-extensions should take place, I > would prefer ... or similar: > > /share/linux/Documentation/sphinx/extensions > > Lets say, you wan't to get in use of the "flat-table" extension. > > Copy (only) the rstFlatTable.py file from my POC extension folder (ignore > other extensions which might be there) ... > > https://github.com/return42/sphkerneldoc/tree/master/doc/extensions > > Now lets say you are writing on a gpu book, it wold be placed in the folder: > > /share/linux/Documentation/sphinx/gpu > > In this gpu-folder you have to place the conf.py config file, needed to > setup the sphinx build environment. > > /share/linux/Documentation/sphinx/gpu/conf.py > > In this conf.py you have to *register* your folder with the extensions. > > <SNIP conf.py> -------- > > import os.path, sys > > EXT_PATH = "../extensions" # the path of extension folder relative to the conf.py file > sys.path.insert(0, os.path.join(os.path.dirname(__file__), EXT_PATH))) > > # now import the "flat-table" extension, it will be self-registering to docutils > > import rstFlatTable > > <SNIP conf.py> -------- > > Thats all, you can run your sphinx-build command and the flat-tables in your > reST sources should be handled as common tables. > > ASIDE: > > You will find similar parts in your conf.py which you have created > with the sphinx-quickstart command. There, you will also find a block > looks like ... > > extensions = [ > 'sphinx.ext.autodoc' > .... > ] > > Don't try to add flat-table extension to this list. This list is a list > of sphinx extensions, we will use it later for other *real* sphinx > extensions. > > A few words about the flat-table extension and a (future) kernel-doc one: > > The flat-table is a pure docutils (the layer below sphinx) extension which > is not application specific, so I will ask for moving it to the docutils > upstream. > > The kernel-doc extension on the other side is a very (very) kernel specific > application, this would never go to sphinx nor docutils upstream. > > --Markus-- > -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
