Convert asciidoc-formatted docs to rst in accordance with Jonathan's and Jani's effort to use sphinx for kernel-doc rendering in 4.8.
Cc: Jonathan Corbet corbet@lwn.net Cc: Jani Nikula jani.nikula@intel.com Signed-off-by: Lukas Wunner lukas@wunner.de --- drivers/platform/x86/apple-gmux.c | 55 +++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 26 deletions(-)
diff --git a/drivers/platform/x86/apple-gmux.c b/drivers/platform/x86/apple-gmux.c index 4034d2d..a66be13 100644 --- a/drivers/platform/x86/apple-gmux.c +++ b/drivers/platform/x86/apple-gmux.c @@ -31,19 +31,21 @@ /** * DOC: Overview * - * :1: http://www.latticesemi.com/en/Products/FPGAandCPLD/LatticeXP2.aspx - * :2: http://www.renesas.com/products/mpumcu/h8s/h8s2100/h8s2113/index.jsp - * * gmux is a microcontroller built into the MacBook Pro to support dual GPUs: - * A {1}[Lattice XP2] on pre-retinas, a {2}[Renesas R4F2113] on retinas. + * A `Lattice XP2`_ on pre-retinas, a `Renesas R4F2113`_ on retinas. * * (The MacPro6,1 2013 also has a gmux, however it is unclear why since it has * dual GPUs but no built-in display.) * * gmux is connected to the LPC bus of the southbridge. Its I/O ports are * accessed differently depending on the microcontroller: Driver functions - * to access a pre-retina gmux are infixed `_pio_`, those for a retina gmux - * are infixed `_index_`. + * to access a pre-retina gmux are infixed ``_pio_``, those for a retina gmux + * are infixed ``_index_``. + * + * .. _Lattice XP2: + * http://www.latticesemi.com/en/Products/FPGAandCPLD/LatticeXP2.aspx + * .. _Renesas R4F2113: + * http://www.renesas.com/products/mpumcu/h8s/h8s2100/h8s2113/index.jsp */
struct apple_gmux_data { @@ -272,15 +274,15 @@ static bool gmux_is_indexed(struct apple_gmux_data *gmux_data) /** * DOC: Backlight control * - * :3: http://www.ti.com/lit/ds/symlink/lp8543.pdf - * :4: http://www.ti.com/lit/ds/symlink/lp8545.pdf - * * On single GPU MacBooks, the PWM signal for the backlight is generated by * the GPU. On dual GPU MacBook Pros by contrast, either GPU may be suspended * to conserve energy. Hence the PWM signal needs to be generated by a separate * backlight driver which is controlled by gmux. The earliest generation - * MBP5 2008/09 uses a {3}[TI LP8543] backlight driver. All newer models - * use a {4}[TI LP8545]. + * MBP5 2008/09 uses a `TI LP8543`_ backlight driver. All newer models + * use a `TI LP8545`_. + * + * .. _TI LP8543: http://www.ti.com/lit/ds/symlink/lp8543.pdf + * .. _TI LP8545: http://www.ti.com/lit/ds/symlink/lp8545.pdf */
static int gmux_get_brightness(struct backlight_device *bd) @@ -312,28 +314,20 @@ static const struct backlight_ops gmux_bl_ops = { /** * DOC: Graphics mux * - * :5: http://pimg-fpiw.uspto.gov/fdd/07/870/086/0.pdf - * :6: http://www.nxp.com/documents/data_sheet/CBTL06141.pdf - * :7: http://www.ti.com/lit/ds/symlink/hd3ss212.pdf - * :8: https://www.pericom.com/assets/Datasheets/PI3VDP12412.pdf - * :9: http://www.ti.com/lit/ds/symlink/sn74lv4066a.pdf - * :10: http://pdf.datasheetarchive.com/indexerfiles/Datasheets-SW16/DSASW00308511.p... - * :11: http://www.ti.com/lit/ds/symlink/ts3ds10224.pdf - * * On pre-retinas, the LVDS outputs of both GPUs feed into gmux which muxes * either of them to the panel. One of the tricks gmux has up its sleeve is * to lengthen the blanking interval of its output during a switch to * synchronize it with the GPU switched to. This allows for a flicker-free - * switch that is imperceptible by the user ({5}[US 8,687,007 B2]). + * switch that is imperceptible by the user (`US 8,687,007 B2`_). * * On retinas, muxing is no longer done by gmux itself, but by a separate * chip which is controlled by gmux. The chip is triple sourced, it is - * either an {6}[NXP CBTL06142], {7}[TI HD3SS212] or {8}[Pericom PI3VDP12412]. + * either an `NXP CBTL06142`_, `TI HD3SS212`_ or `Pericom PI3VDP12412`_. * The panel is driven with eDP instead of LVDS since the pixel clock * required for retina resolution exceeds LVDS' limits. * * Pre-retinas are able to switch the panel's DDC pins separately. - * This is handled by a {9}[TI SN74LV4066A] which is controlled by gmux. + * This is handled by a `TI SN74LV4066A`_ which is controlled by gmux. * The inactive GPU can thus probe the panel's EDID without switching over * the entire panel. Retinas lack this functionality as the chips used for * eDP muxing are incapable of switching the AUX channel separately (see @@ -344,15 +338,15 @@ static const struct backlight_ops gmux_bl_ops = { * * The external DP port is only fully switchable on the first two unibody * MacBook Pro generations, MBP5 2008/09 and MBP6 2010. This is done by an - * {6}[NXP CBTL06141] which is controlled by gmux. It's the predecessor of the + * `NXP CBTL06141`_ which is controlled by gmux. It's the predecessor of the * eDP mux on retinas, the difference being support for 2.7 versus 5.4 Gbit/s. * * The following MacBook Pro generations replaced the external DP port with a * combined DP/Thunderbolt port and lost the ability to switch it between GPUs, * connecting it either to the discrete GPU or the Thunderbolt controller. * Oddly enough, while the full port is no longer switchable, AUX and HPD - * are still switchable by way of an {10}[NXP CBTL03062] (on pre-retinas - * MBP8 2011 and MBP9 2012) or two {11}[TI TS3DS10224] (on retinas) under the + * are still switchable by way of an `NXP CBTL03062`_ (on pre-retinas + * MBP8 2011 and MBP9 2012) or two `TI TS3DS10224`_ (on retinas) under the * control of gmux. Since the integrated GPU is missing the main link, * external displays appear to it as phantoms which fail to link-train. * @@ -365,10 +359,19 @@ static const struct backlight_ops gmux_bl_ops = { * of this feature. * * gmux' initial switch state on bootup is user configurable via the EFI - * variable `gpu-power-prefs-fa4ce28d-b62f-4c99-9cc3-6815686e30f9` (5th byte, + * variable ``gpu-power-prefs-fa4ce28d-b62f-4c99-9cc3-6815686e30f9`` (5th byte, * 1 = IGD, 0 = DIS). Based on this setting, the EFI firmware tells gmux to * switch the panel and the external DP connector and allocates a framebuffer * for the selected GPU. + * + * .. _US 8,687,007 B2: http://pimg-fpiw.uspto.gov/fdd/07/870/086/0.pdf + * .. _NXP CBTL06141: http://www.nxp.com/documents/data_sheet/CBTL06141.pdf + * .. _NXP CBTL06142: http://www.nxp.com/documents/data_sheet/CBTL06141.pdf + * .. _TI HD3SS212: http://www.ti.com/lit/ds/symlink/hd3ss212.pdf + * .. _Pericom PI3VDP12412: https://www.pericom.com/assets/Datasheets/PI3VDP12412.pdf + * .. _TI SN74LV4066A: http://www.ti.com/lit/ds/symlink/sn74lv4066a.pdf + * .. _NXP CBTL03062: http://pdf.datasheetarchive.com/indexerfiles/Datasheets-SW16/DSASW00308511.p... + * .. _TI TS3DS10224: http://www.ti.com/lit/ds/symlink/ts3ds10224.pdf */
static void gmux_read_switch_state(struct apple_gmux_data *gmux_data)
On Mon, Jul 4, 2016 at 1:40 PM, Lukas Wunner lukas@wunner.de wrote:
Convert asciidoc-formatted docs to rst in accordance with Jonathan's and Jani's effort to use sphinx for kernel-doc rendering in 4.8.
Darren, I'm fine with this one. FWIW: Reviewed-by: Andy Shevchenko andy.shevchenko@gmail.com
Cc: Jonathan Corbet corbet@lwn.net Cc: Jani Nikula jani.nikula@intel.com Signed-off-by: Lukas Wunner lukas@wunner.de
drivers/platform/x86/apple-gmux.c | 55 +++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 26 deletions(-)
diff --git a/drivers/platform/x86/apple-gmux.c b/drivers/platform/x86/apple-gmux.c index 4034d2d..a66be13 100644 --- a/drivers/platform/x86/apple-gmux.c +++ b/drivers/platform/x86/apple-gmux.c @@ -31,19 +31,21 @@ /**
- DOC: Overview
- gmux is a microcontroller built into the MacBook Pro to support dual GPUs:
- A {1}[Lattice XP2] on pre-retinas, a {2}[Renesas R4F2113] on retinas.
- A `Lattice XP2`_ on pre-retinas, a `Renesas R4F2113`_ on retinas.
- (The MacPro6,1 2013 also has a gmux, however it is unclear why since it has
- dual GPUs but no built-in display.)
- gmux is connected to the LPC bus of the southbridge. Its I/O ports are
- accessed differently depending on the microcontroller: Driver functions
- to access a pre-retina gmux are infixed `_pio_`, those for a retina gmux
- are infixed `_index_`.
- to access a pre-retina gmux are infixed ``_pio_``, those for a retina gmux
- are infixed ``_index_``.
- .. _Lattice XP2:
http://www.latticesemi.com/en/Products/FPGAandCPLD/LatticeXP2.aspx
- .. _Renesas R4F2113:
*/
http://www.renesas.com/products/mpumcu/h8s/h8s2100/h8s2113/index.jspstruct apple_gmux_data { @@ -272,15 +274,15 @@ static bool gmux_is_indexed(struct apple_gmux_data *gmux_data) /**
- DOC: Backlight control
- On single GPU MacBooks, the PWM signal for the backlight is generated by
- the GPU. On dual GPU MacBook Pros by contrast, either GPU may be suspended
- to conserve energy. Hence the PWM signal needs to be generated by a separate
- backlight driver which is controlled by gmux. The earliest generation
- MBP5 2008/09 uses a {3}[TI LP8543] backlight driver. All newer models
- use a {4}[TI LP8545].
- MBP5 2008/09 uses a `TI LP8543`_ backlight driver. All newer models
- use a `TI LP8545`_.
- .. _TI LP8543: http://www.ti.com/lit/ds/symlink/lp8543.pdf
*/
- .. _TI LP8545: http://www.ti.com/lit/ds/symlink/lp8545.pdf
static int gmux_get_brightness(struct backlight_device *bd) @@ -312,28 +314,20 @@ static const struct backlight_ops gmux_bl_ops = { /**
- DOC: Graphics mux
- On pre-retinas, the LVDS outputs of both GPUs feed into gmux which muxes
- either of them to the panel. One of the tricks gmux has up its sleeve is
- to lengthen the blanking interval of its output during a switch to
- synchronize it with the GPU switched to. This allows for a flicker-free
- switch that is imperceptible by the user ({5}[US 8,687,007 B2]).
- switch that is imperceptible by the user (`US 8,687,007 B2`_).
- On retinas, muxing is no longer done by gmux itself, but by a separate
- chip which is controlled by gmux. The chip is triple sourced, it is
- either an {6}[NXP CBTL06142], {7}[TI HD3SS212] or {8}[Pericom PI3VDP12412].
- either an `NXP CBTL06142`_, `TI HD3SS212`_ or `Pericom PI3VDP12412`_.
- The panel is driven with eDP instead of LVDS since the pixel clock
- required for retina resolution exceeds LVDS' limits.
- Pre-retinas are able to switch the panel's DDC pins separately.
- This is handled by a {9}[TI SN74LV4066A] which is controlled by gmux.
- This is handled by a `TI SN74LV4066A`_ which is controlled by gmux.
- The inactive GPU can thus probe the panel's EDID without switching over
- the entire panel. Retinas lack this functionality as the chips used for
- eDP muxing are incapable of switching the AUX channel separately (see
@@ -344,15 +338,15 @@ static const struct backlight_ops gmux_bl_ops = {
- The external DP port is only fully switchable on the first two unibody
- MacBook Pro generations, MBP5 2008/09 and MBP6 2010. This is done by an
- {6}[NXP CBTL06141] which is controlled by gmux. It's the predecessor of the
- `NXP CBTL06141`_ which is controlled by gmux. It's the predecessor of the
- eDP mux on retinas, the difference being support for 2.7 versus 5.4 Gbit/s.
- The following MacBook Pro generations replaced the external DP port with a
- combined DP/Thunderbolt port and lost the ability to switch it between GPUs,
- connecting it either to the discrete GPU or the Thunderbolt controller.
- Oddly enough, while the full port is no longer switchable, AUX and HPD
- are still switchable by way of an {10}[NXP CBTL03062] (on pre-retinas
- MBP8 2011 and MBP9 2012) or two {11}[TI TS3DS10224] (on retinas) under the
- are still switchable by way of an `NXP CBTL03062`_ (on pre-retinas
- MBP8 2011 and MBP9 2012) or two `TI TS3DS10224`_ (on retinas) under the
- control of gmux. Since the integrated GPU is missing the main link,
- external displays appear to it as phantoms which fail to link-train.
@@ -365,10 +359,19 @@ static const struct backlight_ops gmux_bl_ops = {
- of this feature.
- gmux' initial switch state on bootup is user configurable via the EFI
- variable `gpu-power-prefs-fa4ce28d-b62f-4c99-9cc3-6815686e30f9` (5th byte,
- variable ``gpu-power-prefs-fa4ce28d-b62f-4c99-9cc3-6815686e30f9`` (5th byte,
- 1 = IGD, 0 = DIS). Based on this setting, the EFI firmware tells gmux to
- switch the panel and the external DP connector and allocates a framebuffer
- for the selected GPU.
- .. _US 8,687,007 B2: http://pimg-fpiw.uspto.gov/fdd/07/870/086/0.pdf
- .. _NXP CBTL06141: http://www.nxp.com/documents/data_sheet/CBTL06141.pdf
- .. _NXP CBTL06142: http://www.nxp.com/documents/data_sheet/CBTL06141.pdf
- .. _TI HD3SS212: http://www.ti.com/lit/ds/symlink/hd3ss212.pdf
- .. _Pericom PI3VDP12412: https://www.pericom.com/assets/Datasheets/PI3VDP12412.pdf
- .. _TI SN74LV4066A: http://www.ti.com/lit/ds/symlink/sn74lv4066a.pdf
*/
- .. _TI TS3DS10224: http://www.ti.com/lit/ds/symlink/ts3ds10224.pdf
static void gmux_read_switch_state(struct apple_gmux_data *gmux_data)
2.8.1
-- To unsubscribe from this list: send the line "unsubscribe platform-driver-x86" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Mon, Jul 04, 2016 at 12:40:35PM +0200, Lukas Wunner wrote:
Convert asciidoc-formatted docs to rst in accordance with Jonathan's and Jani's effort to use sphinx for kernel-doc rendering in 4.8.
Somebody help me out here. How do I verify this works and using sphinx? to build the docs? Should I be merging this directly, or is it dependent on something Jon is working on and therefore to be merged by him?
Cc: Jonathan Corbet corbet@lwn.net Cc: Jani Nikula jani.nikula@intel.com Signed-off-by: Lukas Wunner lukas@wunner.de
drivers/platform/x86/apple-gmux.c | 55 +++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 26 deletions(-)
diff --git a/drivers/platform/x86/apple-gmux.c b/drivers/platform/x86/apple-gmux.c index 4034d2d..a66be13 100644 --- a/drivers/platform/x86/apple-gmux.c +++ b/drivers/platform/x86/apple-gmux.c @@ -31,19 +31,21 @@ /**
- DOC: Overview
- gmux is a microcontroller built into the MacBook Pro to support dual GPUs:
- A {1}[Lattice XP2] on pre-retinas, a {2}[Renesas R4F2113] on retinas.
- A `Lattice XP2`_ on pre-retinas, a `Renesas R4F2113`_ on retinas.
- (The MacPro6,1 2013 also has a gmux, however it is unclear why since it has
- dual GPUs but no built-in display.)
- gmux is connected to the LPC bus of the southbridge. Its I/O ports are
- accessed differently depending on the microcontroller: Driver functions
- to access a pre-retina gmux are infixed `_pio_`, those for a retina gmux
- are infixed `_index_`.
- to access a pre-retina gmux are infixed ``_pio_``, those for a retina gmux
- are infixed ``_index_``.
- .. _Lattice XP2:
http://www.latticesemi.com/en/Products/FPGAandCPLD/LatticeXP2.aspx
- .. _Renesas R4F2113:
*/
http://www.renesas.com/products/mpumcu/h8s/h8s2100/h8s2113/index.jspstruct apple_gmux_data { @@ -272,15 +274,15 @@ static bool gmux_is_indexed(struct apple_gmux_data *gmux_data) /**
- DOC: Backlight control
- On single GPU MacBooks, the PWM signal for the backlight is generated by
- the GPU. On dual GPU MacBook Pros by contrast, either GPU may be suspended
- to conserve energy. Hence the PWM signal needs to be generated by a separate
- backlight driver which is controlled by gmux. The earliest generation
- MBP5 2008/09 uses a {3}[TI LP8543] backlight driver. All newer models
- use a {4}[TI LP8545].
- MBP5 2008/09 uses a `TI LP8543`_ backlight driver. All newer models
- use a `TI LP8545`_.
- .. _TI LP8543: http://www.ti.com/lit/ds/symlink/lp8543.pdf
*/
- .. _TI LP8545: http://www.ti.com/lit/ds/symlink/lp8545.pdf
static int gmux_get_brightness(struct backlight_device *bd) @@ -312,28 +314,20 @@ static const struct backlight_ops gmux_bl_ops = { /**
- DOC: Graphics mux
- On pre-retinas, the LVDS outputs of both GPUs feed into gmux which muxes
- either of them to the panel. One of the tricks gmux has up its sleeve is
- to lengthen the blanking interval of its output during a switch to
- synchronize it with the GPU switched to. This allows for a flicker-free
- switch that is imperceptible by the user ({5}[US 8,687,007 B2]).
- switch that is imperceptible by the user (`US 8,687,007 B2`_).
- On retinas, muxing is no longer done by gmux itself, but by a separate
- chip which is controlled by gmux. The chip is triple sourced, it is
- either an {6}[NXP CBTL06142], {7}[TI HD3SS212] or {8}[Pericom PI3VDP12412].
- either an `NXP CBTL06142`_, `TI HD3SS212`_ or `Pericom PI3VDP12412`_.
- The panel is driven with eDP instead of LVDS since the pixel clock
- required for retina resolution exceeds LVDS' limits.
- Pre-retinas are able to switch the panel's DDC pins separately.
- This is handled by a {9}[TI SN74LV4066A] which is controlled by gmux.
- This is handled by a `TI SN74LV4066A`_ which is controlled by gmux.
- The inactive GPU can thus probe the panel's EDID without switching over
- the entire panel. Retinas lack this functionality as the chips used for
- eDP muxing are incapable of switching the AUX channel separately (see
@@ -344,15 +338,15 @@ static const struct backlight_ops gmux_bl_ops = {
- The external DP port is only fully switchable on the first two unibody
- MacBook Pro generations, MBP5 2008/09 and MBP6 2010. This is done by an
- {6}[NXP CBTL06141] which is controlled by gmux. It's the predecessor of the
- `NXP CBTL06141`_ which is controlled by gmux. It's the predecessor of the
- eDP mux on retinas, the difference being support for 2.7 versus 5.4 Gbit/s.
- The following MacBook Pro generations replaced the external DP port with a
- combined DP/Thunderbolt port and lost the ability to switch it between GPUs,
- connecting it either to the discrete GPU or the Thunderbolt controller.
- Oddly enough, while the full port is no longer switchable, AUX and HPD
- are still switchable by way of an {10}[NXP CBTL03062] (on pre-retinas
- MBP8 2011 and MBP9 2012) or two {11}[TI TS3DS10224] (on retinas) under the
- are still switchable by way of an `NXP CBTL03062`_ (on pre-retinas
- MBP8 2011 and MBP9 2012) or two `TI TS3DS10224`_ (on retinas) under the
- control of gmux. Since the integrated GPU is missing the main link,
- external displays appear to it as phantoms which fail to link-train.
@@ -365,10 +359,19 @@ static const struct backlight_ops gmux_bl_ops = {
- of this feature.
- gmux' initial switch state on bootup is user configurable via the EFI
- variable `gpu-power-prefs-fa4ce28d-b62f-4c99-9cc3-6815686e30f9` (5th byte,
- variable ``gpu-power-prefs-fa4ce28d-b62f-4c99-9cc3-6815686e30f9`` (5th byte,
- 1 = IGD, 0 = DIS). Based on this setting, the EFI firmware tells gmux to
- switch the panel and the external DP connector and allocates a framebuffer
- for the selected GPU.
- .. _US 8,687,007 B2: http://pimg-fpiw.uspto.gov/fdd/07/870/086/0.pdf
- .. _NXP CBTL06141: http://www.nxp.com/documents/data_sheet/CBTL06141.pdf
- .. _NXP CBTL06142: http://www.nxp.com/documents/data_sheet/CBTL06141.pdf
- .. _TI HD3SS212: http://www.ti.com/lit/ds/symlink/hd3ss212.pdf
- .. _Pericom PI3VDP12412: https://www.pericom.com/assets/Datasheets/PI3VDP12412.pdf
- .. _TI SN74LV4066A: http://www.ti.com/lit/ds/symlink/sn74lv4066a.pdf
*/
- .. _TI TS3DS10224: http://www.ti.com/lit/ds/symlink/ts3ds10224.pdf
static void gmux_read_switch_state(struct apple_gmux_data *gmux_data)
2.8.1
On Wed, Jul 06, 2016 at 01:40:25PM -0700, Darren Hart wrote:
On Mon, Jul 04, 2016 at 12:40:35PM +0200, Lukas Wunner wrote:
Convert asciidoc-formatted docs to rst in accordance with Jonathan's and Jani's effort to use sphinx for kernel-doc rendering in 4.8.
Somebody help me out here. How do I verify this works and using sphinx? to build the docs?
(1) git remote add l1k https://github.com/l1k/linux.git git fetch l1k git checkout l1k/sphinx-docs (Alternatively: git cherry-pick v4.7-rc6..l1k/sphinx-docs )
(2) sudo apt-get install python-sphinx python-sphinx-rtd-theme
(3) make xmldocs make htmldocs
(4) open Documentation/output/html/index.html click on "VGA Switcheroo", then click on "Handlers" in the navigation pane on the left
The apple-gmux docs are currently asciidoc-formatted. Support for markdown/asciidoc in kerneldoc was an Intel-sponsored effort last year led by Daniel, but never got upstreamed.
After some deliberation the decision was made to use rst instead. Support for it is in docs-next, i.e. will be in 4.8.
Jani has converted the gpu docs to rst and deleted the gpu.tmpl, this is on the drm-intel/for-linux-next branch but not yet in drm-next. Jani and Daniel are both on vacation. Daniel has indicated that he considers sending another drm-intel-next pull when he returns next week, then the rst-formatted gpu docs would land in drm-next: https://lists.freedesktop.org/archives/intel-gfx/2016-June/099114.html
Should I be merging this directly, or is it dependent on something Jon is working on and therefore to be merged by him?
It is not dependent on someone else. You can either merge it directly through your tree or alternatively ack it and have it merged through drm-intel trees by Daniel (+ cc:) next week.
Unfortunately there is currently no branch which contains all the rst patches in docs-next *and* the rst-formatted gpu docs in drm-intel. (Some patches in docs-next are missing from drm-intel/for-linux-next.) That's why I pushed the above-mentioned branch to my GitHub repo, it contains everything needed: https://github.com/l1k/linux/commits/sphinx-docs
Thanks,
Lukas
On Fri, Jul 08, 2016 at 07:49:32AM +0200, Lukas Wunner wrote:
On Wed, Jul 06, 2016 at 01:40:25PM -0700, Darren Hart wrote:
On Mon, Jul 04, 2016 at 12:40:35PM +0200, Lukas Wunner wrote:
Convert asciidoc-formatted docs to rst in accordance with Jonathan's and Jani's effort to use sphinx for kernel-doc rendering in 4.8.
Somebody help me out here. How do I verify this works and using sphinx? to build the docs?
(1) git remote add l1k https://github.com/l1k/linux.git git fetch l1k git checkout l1k/sphinx-docs (Alternatively: git cherry-pick v4.7-rc6..l1k/sphinx-docs )
(2) sudo apt-get install python-sphinx python-sphinx-rtd-theme
(3) make xmldocs make htmldocs
(4) open Documentation/output/html/index.html click on "VGA Switcheroo", then click on "Handlers" in the navigation pane on the left
The apple-gmux docs are currently asciidoc-formatted. Support for markdown/asciidoc in kerneldoc was an Intel-sponsored effort last year led by Daniel, but never got upstreamed.
After some deliberation the decision was made to use rst instead. Support for it is in docs-next, i.e. will be in 4.8.
Jani has converted the gpu docs to rst and deleted the gpu.tmpl, this is on the drm-intel/for-linux-next branch but not yet in drm-next. Jani and Daniel are both on vacation. Daniel has indicated that he considers sending another drm-intel-next pull when he returns next week, then the rst-formatted gpu docs would land in drm-next: https://lists.freedesktop.org/archives/intel-gfx/2016-June/099114.html
Should I be merging this directly, or is it dependent on something Jon is working on and therefore to be merged by him?
It is not dependent on someone else. You can either merge it directly through your tree or alternatively ack it and have it merged through drm-intel trees by Daniel (+ cc:) next week.
Unfortunately there is currently no branch which contains all the rst patches in docs-next *and* the rst-formatted gpu docs in drm-intel. (Some patches in docs-next are missing from drm-intel/for-linux-next.) That's why I pushed the above-mentioned branch to my GitHub repo, it contains everything needed: https://github.com/l1k/linux/commits/sphinx-docs
Probably best to pull this in through drm-misc, which contains docs-next plus the skeleton conversion of the drm docs over to sphinx/rst. Darren, ack on that?
Oh and if you want to take a peek at the pretty docs this gives us:
https://01.org/linuxgraphics/gfx-docs/drm/
This is just the drm part, but if you pull in docs-next there should be even more. Media/tv might also be ready for 4.8. -Daniel
On Tue, Jul 12, 2016 at 03:11:45PM +0200, Daniel Vetter wrote:
On Fri, Jul 08, 2016 at 07:49:32AM +0200, Lukas Wunner wrote:
On Wed, Jul 06, 2016 at 01:40:25PM -0700, Darren Hart wrote:
On Mon, Jul 04, 2016 at 12:40:35PM +0200, Lukas Wunner wrote:
Convert asciidoc-formatted docs to rst in accordance with Jonathan's and Jani's effort to use sphinx for kernel-doc rendering in 4.8.
Somebody help me out here. How do I verify this works and using sphinx? to build the docs?
(1) git remote add l1k https://github.com/l1k/linux.git git fetch l1k git checkout l1k/sphinx-docs (Alternatively: git cherry-pick v4.7-rc6..l1k/sphinx-docs )
(2) sudo apt-get install python-sphinx python-sphinx-rtd-theme
(3) make xmldocs make htmldocs
(4) open Documentation/output/html/index.html click on "VGA Switcheroo", then click on "Handlers" in the navigation pane on the left
The apple-gmux docs are currently asciidoc-formatted. Support for markdown/asciidoc in kerneldoc was an Intel-sponsored effort last year led by Daniel, but never got upstreamed.
After some deliberation the decision was made to use rst instead. Support for it is in docs-next, i.e. will be in 4.8.
Jani has converted the gpu docs to rst and deleted the gpu.tmpl, this is on the drm-intel/for-linux-next branch but not yet in drm-next. Jani and Daniel are both on vacation. Daniel has indicated that he considers sending another drm-intel-next pull when he returns next week, then the rst-formatted gpu docs would land in drm-next: https://lists.freedesktop.org/archives/intel-gfx/2016-June/099114.html
Should I be merging this directly, or is it dependent on something Jon is working on and therefore to be merged by him?
It is not dependent on someone else. You can either merge it directly through your tree or alternatively ack it and have it merged through drm-intel trees by Daniel (+ cc:) next week.
Unfortunately there is currently no branch which contains all the rst patches in docs-next *and* the rst-formatted gpu docs in drm-intel. (Some patches in docs-next are missing from drm-intel/for-linux-next.) That's why I pushed the above-mentioned branch to my GitHub repo, it contains everything needed: https://github.com/l1k/linux/commits/sphinx-docs
Probably best to pull this in through drm-misc, which contains docs-next plus the skeleton conversion of the drm docs over to sphinx/rst. Darren, ack on that?
Acked-by: Darren Hart dvhart@linux.intel.com
I've dropped this from my testing branch (I never pushed it to my next branch) and will leave it to you to pull in.
Oh and if you want to take a peek at the pretty docs this gives us:
Very nice.
This is just the drm part, but if you pull in docs-next there should be even more. Media/tv might also be ready for 4.8.
-Daniel
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
On Fri, Jul 22, 2016 at 01:19:12PM -0700, Darren Hart wrote:
On Tue, Jul 12, 2016 at 03:11:45PM +0200, Daniel Vetter wrote:
On Fri, Jul 08, 2016 at 07:49:32AM +0200, Lukas Wunner wrote:
On Wed, Jul 06, 2016 at 01:40:25PM -0700, Darren Hart wrote:
On Mon, Jul 04, 2016 at 12:40:35PM +0200, Lukas Wunner wrote:
Convert asciidoc-formatted docs to rst in accordance with Jonathan's and Jani's effort to use sphinx for kernel-doc rendering in 4.8.
Somebody help me out here. How do I verify this works and using sphinx? to build the docs?
(1) git remote add l1k https://github.com/l1k/linux.git git fetch l1k git checkout l1k/sphinx-docs (Alternatively: git cherry-pick v4.7-rc6..l1k/sphinx-docs )
(2) sudo apt-get install python-sphinx python-sphinx-rtd-theme
(3) make xmldocs make htmldocs
(4) open Documentation/output/html/index.html click on "VGA Switcheroo", then click on "Handlers" in the navigation pane on the left
The apple-gmux docs are currently asciidoc-formatted. Support for markdown/asciidoc in kerneldoc was an Intel-sponsored effort last year led by Daniel, but never got upstreamed.
After some deliberation the decision was made to use rst instead. Support for it is in docs-next, i.e. will be in 4.8.
Jani has converted the gpu docs to rst and deleted the gpu.tmpl, this is on the drm-intel/for-linux-next branch but not yet in drm-next. Jani and Daniel are both on vacation. Daniel has indicated that he considers sending another drm-intel-next pull when he returns next week, then the rst-formatted gpu docs would land in drm-next: https://lists.freedesktop.org/archives/intel-gfx/2016-June/099114.html
Should I be merging this directly, or is it dependent on something Jon is working on and therefore to be merged by him?
It is not dependent on someone else. You can either merge it directly through your tree or alternatively ack it and have it merged through drm-intel trees by Daniel (+ cc:) next week.
Unfortunately there is currently no branch which contains all the rst patches in docs-next *and* the rst-formatted gpu docs in drm-intel. (Some patches in docs-next are missing from drm-intel/for-linux-next.) That's why I pushed the above-mentioned branch to my GitHub repo, it contains everything needed: https://github.com/l1k/linux/commits/sphinx-docs
Probably best to pull this in through drm-misc, which contains docs-next plus the skeleton conversion of the drm docs over to sphinx/rst. Darren, ack on that?
Acked-by: Darren Hart dvhart@linux.intel.com
I've dropped this from my testing branch (I never pushed it to my next branch) and will leave it to you to pull in.
Thanks, applied to drm-misc. I'll try to still sneak it into 4.8. -Daniel
dri-devel@lists.freedesktop.org
-
Andy Shevchenko -
Daniel Vetter -
Darren Hart -
Lukas Wunner