Skip to contentSkip to conversation

Kernel documentation discussions

Ksummit-discuss Mauro Carvalho Chehab 1 participant 1 message Oct 31, 2016

lore
Share & tools
lore
#0 lore raw

Hi Jon,

As I wake up too early today, due to the time zone differences, and inspired by your article about documentation at lwn (https://lwn.net/Articles/704613/),
I decided to take some time and do some brain storming to help with the KS discussions. Feel free to pick the good things here, and discard the rest ;)

This is based on the work I've doing on the past few months with the media conversion, and, mainly my work with regards to development process and admin guides. Btw, I wrote some articles to document the challenges on those two books that might be interesting for the discussions too:
https://blogs.s-osg.org/creation-linux-kernel-users-manual/
https://blogs.s-osg.org/documenting-linux-kernel-development-process/

They're part of an attempt from my side As to document the challenges I'm having with the documentation conversion:
https://blogs.s-osg.org/new-improved-linux-kernel-media-documentation/

I'm c/c Greg, as I listed several things related to the ABI documentation.

ReST conversion - some stats
============================

If I got it right, this is the current status

- about 600 files on ReST
- 305 ABI files + ABI/README
- 32 files with translations to Japanase, Korean and Chinese;
- 30 files on DocBook
- about 6k plain files to be converted, being 97 files at the Documentation/ root directory (96 after EDAC conversion, with I did already).

There's still an elephant at the room: who will do the remaining conversions :)

Items requiring some sort of definition
=======================================

(probably, we won't have time on KS regular time to discuss all of them)

Please notice that this is a brainstorm list, with items I remembered, with no particular order.

1) Rename: Documentation -> doc (or docs)?
- Change the location for the translated documents?

2) What to do with the remaining 96 files under Documentation?

I tried my best to put the "lose" files at Documentation/ under either admin-guide or process. Yet, I skip several files because I didn't know for sure what to do with them...

- There are some stuff there that could probably be discarded (for example: eisa.txt);
- There are some stuff there that probably belong to driver-api or to some other subsystem (like, for example video-output.txt, with seems to be some GPU documentation);
- There are some stuff there that contains both admin documentation and driver documentation (like, for example ntb.txt, with contains ABI documentation, module parameters,
- There are files there with even code examples for userspace tools, like: cpu-load.txt
- On most cases, some work is needed for those files that are still there...

3) long-term strategy for 00-INDEX:

On converted files, the index will be auto-generated, and the index.rst files will contain the documents. Should we keep maintaining the 00-INDEX files in long term? or should we do something else:
move it to /README?
remove it?
put only directories there?

4) Should we add a generic Sphinx module to run scripts (e. g.) kernel-cmd?

- If so, what would be the rules for using it?

My suggestion it to block it to run only scripts under an specific directory (like Documentation/sphinx) and selected scripts under ./scripts (like ./get-maintainers and ./kernel-doc). Scripts that will be run should be submitted to kernel-doc ML and acked-by the documentation maintainer or merged via documentation tree.

5) ABI parsing via script;
- IMHO, this the onlg viable way of handling it;
- Perhaps add part of the contents of ABI/README at the rst file;
- ABI format: sort, sub-chapters, etc;
- ABI files with a "header" text;
- Should ABI be kept under docs, if not converted to ReST?
- Should we use a new tag to allow descriptions in ReST format?

6) MAINTAINERS file
- Should we add it to process documentation? IMHO, we should, at least a "short" version of it, with the name/location of the modules, the git tree and the ML for submissions.

7) PDF, LaTeX and Math extension

Can it be improved?

Cheers,
Mauro