Em Fri, 21 Jun 2019 10:04:41 -0300 Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> escreveu: > Em Fri, 21 Jun 2019 09:39:15 -0300 > Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> escreveu: > > > Em Fri, 21 Jun 2019 09:32:00 -0300 > > Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> escreveu: > > > > > Hi Greg, > > > > > > As you proposed to give it a try on removing the escape code from the > > > script which parses the ReST file, I changed a few things there, > > > adding the capability of selectively enabling to output an ABI sub-dir > > > without escaping things that would crash Sphinx. > > > > > > PS.: As for now this is just a RFC, I'm not getting the ABI file > > > maintainers, copying just LKML, linux-doc ML, plus you and Jon. > > > > > > I also manually fixed the contents of ABI/stable, in order for it to > > > pass without causing troubles. > > > > > > I added all patches from ABI and features at this branch: > > > > > > https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.1 > > > > > > The html output is at https://www.infradead.org/~mchehab/rst_features/, > > > and you can see the resulting ABI guide on: > > > > > > https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html > > > > > > No Sphinx crashes/warnings happen when building it. > > > > > > That's my personal notes about such work: > > > > > > 1) Documentation/ABI/stable/sysfs-class-infiniband > > > > > > It had some title captions inside it, like: > > > > > > Errors info: > > > ----------- > > > > > > For one of the "What:" > > > > > > Sphinx is really pick with title markups. As the entire Documentation/stable is > > > parsed as if it were a single document, there should be a coherency on what > > > character is used to markup a level-one title. I mean, if one document uses: > > > > > > foo > > > ---- > > > > > > For the first level, all other documents should use "---...-" as well. > > > > > > The alternative would be to have one entry for every single file at > > > Documentation/admin-guide/abi-*.rst, with, IMHO, it would be a lot > > > harder to maintain. > > > > > > So, the best seems to let clear at ABI/README about how titles/subtitles > > > should be used inside files, if any. > > > > > > 2) Some documents there use a "Values:" tag, with is not defined as a > > > valid one at ABI/README. The script handles it as part of the description, > > > so no harm done; > > > > > > 3) Among the 47 files under ABI/stable, 14 of them names the file > > > contents, using a valid ReST markup for the document title. That is shown > > > at the index at: > > > > > > https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html > > > > > > > > > - ABI stable symbols > > > > > > - sysfs interface for Mellanox ConnectX HCA IB driver (mlx4) > > > - sysfs interface for Intel IB driver qib > > > - sysfs interface for Intel(R) X722 iWARP i40iw driver > > > - sysfs interface for QLogic qedr NIC Driver > > > - sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes) > > > - sysfs interface for Cisco VIC (usNIC) Verbs Driver > > > - sysfs interface for Chelsio T3 RDMA Driver (cxgb3) > > > - sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4) > > > - sysfs interface for Intel Omni-Path driver (HFI1) > > > - sysfs interface for VMware Paravirtual RDMA driver > > > - sysfs interface for Mellanox Connect-IB HCA driver mlx5 > > > - sysfs interface for Emulex RoCE HCA Driver > > > - sysfs interface for Broadcom NetXtreme-E RoCE driver > > > - sysfs interface for Mellanox IB HCA low-level driver (mthca) > > > > > > I liked that, but ideally all ABI files should either use it or not. > > > > > > 4) I was expecting to have troubles with asterisk characters inside the > > > ABI files. That was not the case: I had to escape just one occurrence on > > > a single file of the 47 ones inside ABI/stable. > > > > > > - > > > > > > My conclusion from this experiment is that it is worth cleaning the ABI > > > files for them to be parsed without needing to escape non-ReST compliant > > > parts of the ABI file. > > > > > > Perhaps we could keep rst-compliant the stable, obsolete and removed > > > directories only, and gradually moving stuff from ABI/testing to ABI/stable, > > > while fixing them to be rst-compliant. > > > > Btw, adding :rst: to kernel-abi markup at abi-obsolete.rst and > > abi-removed.rst produced just two warnings: > > > > get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation. > > get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1692: WARNING: Block quote ends without a blank line; unexpected unindent. > > > > I'll fix those too at my repository. > > > > I suspect, however, that Documentation/ABI/testing with its 353 files will > > require a lot more care. > > Disabling the escaping logic for ABI/testing won't cause crashes with Sphinx > 1.4.9 (it will probably cause more harm on newer versions), but will require > a lot care, as it introduces 248 new errors/warnings: And they come from 71 different files (list enclosed). I didn't look on them, and I'll stop handling here for now, as I need to handle some other stuff. Yet, manually fixing those 71 ABI files doesn't sound a too hard work. It can probably be done on a single day. So, I suspect we could enable :rst: and manually fix those. Regards, Mauro - Files that have issues when assuming that they're ReST friendly: configfs-spear-pcie-gadget configfs-usb-gadget configfs-usb-gadget-hid configfs-usb-gadget-rndis configfs-usb-gadget-uac1 configfs-usb-gadget-uvc debugfs-ec debugfs-pktcdvd dev-kmsg evm ima_policy procfs-diskstats sysfs-block sysfs-block-device sysfs-bus-acpi sysfs-bus-event_source-devices-format sysfs-bus-i2c-devices-pca954x sysfs-bus-iio sysfs-bus-iio-adc-envelope-detector sysfs-bus-iio-cros-ec sysfs-bus-iio-dfsdm-adc-stm32 sysfs-bus-iio-lptimer-stm32 sysfs-bus-iio-magnetometer-hmc5843 sysfs-bus-iio-temperature-max31856 sysfs-bus-iio-timer-stm32 sysfs-bus-intel_th-devices-msc sysfs-bus-rapidio sysfs-bus-thunderbolt sysfs-bus-usb sysfs-bus-usb-devices-usbsevseg sysfs-bus-vfio-mdev sysfs-class-cxl sysfs-class-led sysfs-class-mic.txt sysfs-class-ocxl sysfs-class-power sysfs-class-power-twl4030 sysfs-class-rc sysfs-class-scsi_host sysfs-class-typec sysfs-devices-platform-ACPI-TAD sysfs-devices-platform-docg3 sysfs-devices-platform-sh_mobile_lcdc_fb sysfs-devices-system-cpu sysfs-devices-system-ibm-rtl sysfs-driver-bd9571mwv-regulator sysfs-driver-genwqe sysfs-driver-hid-logitech-lg4ff sysfs-driver-hid-wiimote sysfs-driver-samsung-laptop sysfs-driver-toshiba_acpi sysfs-driver-toshiba_haps sysfs-driver-wacom sysfs-firmware-acpi sysfs-firmware-dmi-entries sysfs-firmware-gsmi sysfs-firmware-memmap sysfs-fs-ext4 sysfs-hypervisor-xen sysfs-kernel-boot_params sysfs-kernel-mm-hugepages sysfs-platform-asus-laptop sysfs-platform-asus-wmi sysfs-platform-at91 sysfs-platform-eeepc-laptop sysfs-platform-ideapad-laptop sysfs-platform-intel-wmi-thunderbolt sysfs-platform-sst-atom sysfs-platform-usbip-vudc sysfs-ptp sysfs-uevent Thanks, Mauro
