You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@qpid.apache.org by Alan Conway <ac...@redhat.com> on 2016/06/21 17:01:53 UTC
Review Request 49031: DISPATCH-399: Converted documentation to
asciidoc format.
-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/49031/
-----------------------------------------------------------
Review request for qpid, Ganesh Murthy, Justin Ross, mick goulish, and Ted Ross.
Repository: qpid-dispatch
Description
-------
Code and pre-renedered HTML available at file:///home/aconway/alanconway.github.io
Converted .rst documentation files to .adoc format.
asciidoc format is becoming more popular for documentation and has several
advantages over RST + sphinx.
- Mature, widely-used DocBook model without painful XML syntax
- Multi-file documents and entity substitution are standard in asciidoc
(Sphinx has non-standard extensions, but not defined by RST)
- simpler, more flexible tools, fewer generation steps.
Conversion from asciidoc was straightforward using pandoc. Most of the work was
tweaking the doc generators and CMake.
Diffs
-----
doc/CMakeLists.txt 556b2cfb59cf5db1d5b7cfb7f59d961f743fa7e1
doc/README dc5c98a6b172621cd3ae424dd7a709bc53d72147
doc/api/CMakeLists.txt 345035cf2215fcc0813053da9c50912197e24888
doc/api/README 8bb80fa57b9c665a4a8c946b6cda09e54b7dca23
doc/api/doxygen.in 798973b65ed0110b5bf52d57734b9b6ca98b806d
doc/asciidoc.conf.in PRE-CREATION
doc/book/addressing.adoc PRE-CREATION
doc/book/addressing.rst aa63dbe63c8fc3b5e5608f0f600ef4beda51afd4
doc/book/amqp-mapping.adoc PRE-CREATION
doc/book/amqp-mapping.rst 465acd9f9949bef8a93f3d489a1084d864339dd5
doc/book/auto_links.adoc PRE-CREATION
doc/book/auto_links.rst 822cbdd7714b5ada6cf030f46d7a82ddcd30dcde
doc/book/basic_usage.adoc PRE-CREATION
doc/book/basic_usage.rst 232991a89ad21c6577c0e812706803435c41d6b6
doc/book/book.adoc PRE-CREATION
doc/book/book.rst f333001264266b2aec7da6d5218494908bb1a504
doc/book/client_compatibility.adoc PRE-CREATION
doc/book/client_compatibility.rst 6b0150fb0616de5d51fed043a9d1f2957c8daa96
doc/book/console.rst e2a13675281e739ef9f5b8e67ca3804c2548a6fd
doc/book/console_installation.adoc PRE-CREATION
doc/book/console_installation.rst 6484d0525cda159ea323bc11cee7430116d6e758
doc/book/console_operation.adoc PRE-CREATION
doc/book/console_operation.rst 1d382b5daad5b3934f66bacebc5e44dfd2627dad
doc/book/console_overview.adoc PRE-CREATION
doc/book/console_overview.rst 86445552e086f503b29bea6ce38726125426eac8
doc/book/default_config.adoc PRE-CREATION
doc/book/default_config.rst 374d69e6f2b7309220b8e9e5959c6c768d29929a
doc/book/introduction.rst 5e532ab09ca34e0655109c60e872051b2b662260
doc/book/link_routing.adoc PRE-CREATION
doc/book/link_routing.rst f9a023ebcffb227f71d2a68f1270bd6abfd2cada
doc/book/schema_rst.py 5120766eb85f5381d0279b057a2a505a5d1b6198
doc/book/technical_details.rst bce80a47ebaf1bbfff2dfe9cc135bc7b82df9903
doc/book/tools.adoc PRE-CREATION
doc/book/tools.rst a31757f6bba875bc8cddc0991a769276f4f926d2
doc/book/using.rst 474758d1a139e7bdb5fe470f5da192ade1039b61
doc/conf.py.in 43c1037a16827fbdfc913b0255fe2a9da6c02bcd
doc/index.adoc PRE-CREATION
doc/index.rst 0e00953047631ec9763bc5f9d23f50852e36ab10
doc/man/help2rst.py 98feea436e5a90590a55a894afa48bfe9a6c0e2f
doc/man/qdmanage.8.adoc PRE-CREATION
doc/man/qdmanage.rst.in c23302d58c35ac2187e33d001192752d726cdac3
doc/man/qdrouterd.8.adoc PRE-CREATION
doc/man/qdrouterd.rst.in 32741cef7d8ff2a66924045cfb1c9f464e7e2df6
doc/man/qdrouterd_conf_man.py 25302aef30c059116bf7674a10fc9d28a22e00a0
doc/man/qdstat.8.adoc PRE-CREATION
doc/man/qdstat.rst 935642c7a1c867df427611dcaa794301d9f16531
doc/notes/code-conventions.rst 21fcf0685b744b553abf7c00c8689713ff32c5f7
doc/notes/code-conventions.txt PRE-CREATION
doc/themes/bare/layout.html 113cf1a4b00ca1d7d7125841d1172513ca3ebb81
doc/themes/bare/theme.conf 2b3c705f4eed6a6096ccb1f00006336f31d97200
python/qpid_dispatch/management/qdrouter.json 197ec97f8f7332fad7350f9bf0ef06dc431a43bd
python/qpid_dispatch_internal/management/schema_doc.py 36c3faf7b1361f347b6b7b81f1efb33e6bbb0610
Diff: https://reviews.apache.org/r/49031/diff/
Testing
-------
manual review of docs.
Thanks,
Alan Conway
Re: Review Request 49031: DISPATCH-399: Converted documentation to
asciidoc format.
Posted by Alan Conway <ac...@redhat.com>.
> On June 22, 2016, 9:04 p.m., Ganesh Murthy wrote:
> > doc/CMakeLists.txt, line 190
> > <https://reviews.apache.org/r/49031/diff/1/?file=1426689#file1426689line190>
> >
> > The PDF looks great. Can you also please add a link to a single page HTML next to the PDF link
There is only single page HTML now. That's the asciidoc default and IMO it's all we need - it is simple, searchable and has a TOC. The sphinx multi-page setup with the search box and side-panels was very fancy, but not really more useable.
- Alan
-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/49031/#review139131
-----------------------------------------------------------
On June 21, 2016, 5:02 p.m., Alan Conway wrote:
>
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/49031/
> -----------------------------------------------------------
>
> (Updated June 21, 2016, 5:02 p.m.)
>
>
> Review request for qpid, Ganesh Murthy, Justin Ross, mick goulish, and Ted Ross.
>
>
> Repository: qpid-dispatch
>
>
> Description
> -------
>
> Code and pre-renedered HTML available at http://alanconway.github.io
>
> Converted .rst documentation files to .adoc format.
>
> asciidoc format is becoming more popular for documentation and has several
> advantages over RST + sphinx.
>
> - Mature, widely-used DocBook model without painful XML syntax
> - Multi-file documents and entity substitution are standard in asciidoc
> (Sphinx has non-standard extensions, but not defined by RST)
> - simpler, more flexible tools, fewer generation steps.
>
> Conversion from asciidoc was straightforward using pandoc. Most of the work was
> tweaking the doc generators and CMake.
>
>
> Diffs
> -----
>
> doc/CMakeLists.txt 556b2cfb59cf5db1d5b7cfb7f59d961f743fa7e1
> doc/README dc5c98a6b172621cd3ae424dd7a709bc53d72147
> doc/api/CMakeLists.txt 345035cf2215fcc0813053da9c50912197e24888
> doc/api/README 8bb80fa57b9c665a4a8c946b6cda09e54b7dca23
> doc/api/doxygen.in 798973b65ed0110b5bf52d57734b9b6ca98b806d
> doc/asciidoc.conf.in PRE-CREATION
> doc/book/addressing.adoc PRE-CREATION
> doc/book/addressing.rst aa63dbe63c8fc3b5e5608f0f600ef4beda51afd4
> doc/book/amqp-mapping.adoc PRE-CREATION
> doc/book/amqp-mapping.rst 465acd9f9949bef8a93f3d489a1084d864339dd5
> doc/book/auto_links.adoc PRE-CREATION
> doc/book/auto_links.rst 822cbdd7714b5ada6cf030f46d7a82ddcd30dcde
> doc/book/basic_usage.adoc PRE-CREATION
> doc/book/basic_usage.rst 232991a89ad21c6577c0e812706803435c41d6b6
> doc/book/book.adoc PRE-CREATION
> doc/book/book.rst f333001264266b2aec7da6d5218494908bb1a504
> doc/book/client_compatibility.adoc PRE-CREATION
> doc/book/client_compatibility.rst 6b0150fb0616de5d51fed043a9d1f2957c8daa96
> doc/book/console.rst e2a13675281e739ef9f5b8e67ca3804c2548a6fd
> doc/book/console_installation.adoc PRE-CREATION
> doc/book/console_installation.rst 6484d0525cda159ea323bc11cee7430116d6e758
> doc/book/console_operation.adoc PRE-CREATION
> doc/book/console_operation.rst 1d382b5daad5b3934f66bacebc5e44dfd2627dad
> doc/book/console_overview.adoc PRE-CREATION
> doc/book/console_overview.rst 86445552e086f503b29bea6ce38726125426eac8
> doc/book/default_config.adoc PRE-CREATION
> doc/book/default_config.rst 374d69e6f2b7309220b8e9e5959c6c768d29929a
> doc/book/introduction.rst 5e532ab09ca34e0655109c60e872051b2b662260
> doc/book/link_routing.adoc PRE-CREATION
> doc/book/link_routing.rst f9a023ebcffb227f71d2a68f1270bd6abfd2cada
> doc/book/schema_rst.py 5120766eb85f5381d0279b057a2a505a5d1b6198
> doc/book/technical_details.rst bce80a47ebaf1bbfff2dfe9cc135bc7b82df9903
> doc/book/tools.adoc PRE-CREATION
> doc/book/tools.rst a31757f6bba875bc8cddc0991a769276f4f926d2
> doc/book/using.rst 474758d1a139e7bdb5fe470f5da192ade1039b61
> doc/conf.py.in 43c1037a16827fbdfc913b0255fe2a9da6c02bcd
> doc/index.adoc PRE-CREATION
> doc/index.rst 0e00953047631ec9763bc5f9d23f50852e36ab10
> doc/man/help2rst.py 98feea436e5a90590a55a894afa48bfe9a6c0e2f
> doc/man/qdmanage.8.adoc PRE-CREATION
> doc/man/qdmanage.rst.in c23302d58c35ac2187e33d001192752d726cdac3
> doc/man/qdrouterd.8.adoc PRE-CREATION
> doc/man/qdrouterd.rst.in 32741cef7d8ff2a66924045cfb1c9f464e7e2df6
> doc/man/qdrouterd_conf_man.py 25302aef30c059116bf7674a10fc9d28a22e00a0
> doc/man/qdstat.8.adoc PRE-CREATION
> doc/man/qdstat.rst 935642c7a1c867df427611dcaa794301d9f16531
> doc/notes/code-conventions.rst 21fcf0685b744b553abf7c00c8689713ff32c5f7
> doc/notes/code-conventions.txt PRE-CREATION
> doc/themes/bare/layout.html 113cf1a4b00ca1d7d7125841d1172513ca3ebb81
> doc/themes/bare/theme.conf 2b3c705f4eed6a6096ccb1f00006336f31d97200
> python/qpid_dispatch/management/qdrouter.json 197ec97f8f7332fad7350f9bf0ef06dc431a43bd
> python/qpid_dispatch_internal/management/schema_doc.py 36c3faf7b1361f347b6b7b81f1efb33e6bbb0610
>
> Diff: https://reviews.apache.org/r/49031/diff/
>
>
> Testing
> -------
>
> manual review of docs.
>
>
> Thanks,
>
> Alan Conway
>
>
Re: Review Request 49031: DISPATCH-399: Converted documentation to
asciidoc format.
Posted by Ganesh Murthy <gm...@redhat.com>.
-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/49031/#review139131
-----------------------------------------------------------
doc/CMakeLists.txt (line 119)
<https://reviews.apache.org/r/49031/#comment204278>
The PDF looks great. Can you also please add a link to a single page HTML next to the PDF link
- Ganesh Murthy
On June 21, 2016, 5:02 p.m., Alan Conway wrote:
>
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/49031/
> -----------------------------------------------------------
>
> (Updated June 21, 2016, 5:02 p.m.)
>
>
> Review request for qpid, Ganesh Murthy, Justin Ross, mick goulish, and Ted Ross.
>
>
> Repository: qpid-dispatch
>
>
> Description
> -------
>
> Code and pre-renedered HTML available at http://alanconway.github.io
>
> Converted .rst documentation files to .adoc format.
>
> asciidoc format is becoming more popular for documentation and has several
> advantages over RST + sphinx.
>
> - Mature, widely-used DocBook model without painful XML syntax
> - Multi-file documents and entity substitution are standard in asciidoc
> (Sphinx has non-standard extensions, but not defined by RST)
> - simpler, more flexible tools, fewer generation steps.
>
> Conversion from asciidoc was straightforward using pandoc. Most of the work was
> tweaking the doc generators and CMake.
>
>
> Diffs
> -----
>
> doc/CMakeLists.txt 556b2cfb59cf5db1d5b7cfb7f59d961f743fa7e1
> doc/README dc5c98a6b172621cd3ae424dd7a709bc53d72147
> doc/api/CMakeLists.txt 345035cf2215fcc0813053da9c50912197e24888
> doc/api/README 8bb80fa57b9c665a4a8c946b6cda09e54b7dca23
> doc/api/doxygen.in 798973b65ed0110b5bf52d57734b9b6ca98b806d
> doc/asciidoc.conf.in PRE-CREATION
> doc/book/addressing.adoc PRE-CREATION
> doc/book/addressing.rst aa63dbe63c8fc3b5e5608f0f600ef4beda51afd4
> doc/book/amqp-mapping.adoc PRE-CREATION
> doc/book/amqp-mapping.rst 465acd9f9949bef8a93f3d489a1084d864339dd5
> doc/book/auto_links.adoc PRE-CREATION
> doc/book/auto_links.rst 822cbdd7714b5ada6cf030f46d7a82ddcd30dcde
> doc/book/basic_usage.adoc PRE-CREATION
> doc/book/basic_usage.rst 232991a89ad21c6577c0e812706803435c41d6b6
> doc/book/book.adoc PRE-CREATION
> doc/book/book.rst f333001264266b2aec7da6d5218494908bb1a504
> doc/book/client_compatibility.adoc PRE-CREATION
> doc/book/client_compatibility.rst 6b0150fb0616de5d51fed043a9d1f2957c8daa96
> doc/book/console.rst e2a13675281e739ef9f5b8e67ca3804c2548a6fd
> doc/book/console_installation.adoc PRE-CREATION
> doc/book/console_installation.rst 6484d0525cda159ea323bc11cee7430116d6e758
> doc/book/console_operation.adoc PRE-CREATION
> doc/book/console_operation.rst 1d382b5daad5b3934f66bacebc5e44dfd2627dad
> doc/book/console_overview.adoc PRE-CREATION
> doc/book/console_overview.rst 86445552e086f503b29bea6ce38726125426eac8
> doc/book/default_config.adoc PRE-CREATION
> doc/book/default_config.rst 374d69e6f2b7309220b8e9e5959c6c768d29929a
> doc/book/introduction.rst 5e532ab09ca34e0655109c60e872051b2b662260
> doc/book/link_routing.adoc PRE-CREATION
> doc/book/link_routing.rst f9a023ebcffb227f71d2a68f1270bd6abfd2cada
> doc/book/schema_rst.py 5120766eb85f5381d0279b057a2a505a5d1b6198
> doc/book/technical_details.rst bce80a47ebaf1bbfff2dfe9cc135bc7b82df9903
> doc/book/tools.adoc PRE-CREATION
> doc/book/tools.rst a31757f6bba875bc8cddc0991a769276f4f926d2
> doc/book/using.rst 474758d1a139e7bdb5fe470f5da192ade1039b61
> doc/conf.py.in 43c1037a16827fbdfc913b0255fe2a9da6c02bcd
> doc/index.adoc PRE-CREATION
> doc/index.rst 0e00953047631ec9763bc5f9d23f50852e36ab10
> doc/man/help2rst.py 98feea436e5a90590a55a894afa48bfe9a6c0e2f
> doc/man/qdmanage.8.adoc PRE-CREATION
> doc/man/qdmanage.rst.in c23302d58c35ac2187e33d001192752d726cdac3
> doc/man/qdrouterd.8.adoc PRE-CREATION
> doc/man/qdrouterd.rst.in 32741cef7d8ff2a66924045cfb1c9f464e7e2df6
> doc/man/qdrouterd_conf_man.py 25302aef30c059116bf7674a10fc9d28a22e00a0
> doc/man/qdstat.8.adoc PRE-CREATION
> doc/man/qdstat.rst 935642c7a1c867df427611dcaa794301d9f16531
> doc/notes/code-conventions.rst 21fcf0685b744b553abf7c00c8689713ff32c5f7
> doc/notes/code-conventions.txt PRE-CREATION
> doc/themes/bare/layout.html 113cf1a4b00ca1d7d7125841d1172513ca3ebb81
> doc/themes/bare/theme.conf 2b3c705f4eed6a6096ccb1f00006336f31d97200
> python/qpid_dispatch/management/qdrouter.json 197ec97f8f7332fad7350f9bf0ef06dc431a43bd
> python/qpid_dispatch_internal/management/schema_doc.py 36c3faf7b1361f347b6b7b81f1efb33e6bbb0610
>
> Diff: https://reviews.apache.org/r/49031/diff/
>
>
> Testing
> -------
>
> manual review of docs.
>
>
> Thanks,
>
> Alan Conway
>
>
Re: Review Request 49031: DISPATCH-399: Converted documentation to
asciidoc format.
Posted by Alan Conway <ac...@redhat.com>.
-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/49031/
-----------------------------------------------------------
(Updated June 21, 2016, 5:02 p.m.)
Review request for qpid, Ganesh Murthy, Justin Ross, mick goulish, and Ted Ross.
Repository: qpid-dispatch
Description (updated)
-------
Code and pre-renedered HTML available at http://alanconway.github.io
Converted .rst documentation files to .adoc format.
asciidoc format is becoming more popular for documentation and has several
advantages over RST + sphinx.
- Mature, widely-used DocBook model without painful XML syntax
- Multi-file documents and entity substitution are standard in asciidoc
(Sphinx has non-standard extensions, but not defined by RST)
- simpler, more flexible tools, fewer generation steps.
Conversion from asciidoc was straightforward using pandoc. Most of the work was
tweaking the doc generators and CMake.
Diffs
-----
doc/CMakeLists.txt 556b2cfb59cf5db1d5b7cfb7f59d961f743fa7e1
doc/README dc5c98a6b172621cd3ae424dd7a709bc53d72147
doc/api/CMakeLists.txt 345035cf2215fcc0813053da9c50912197e24888
doc/api/README 8bb80fa57b9c665a4a8c946b6cda09e54b7dca23
doc/api/doxygen.in 798973b65ed0110b5bf52d57734b9b6ca98b806d
doc/asciidoc.conf.in PRE-CREATION
doc/book/addressing.adoc PRE-CREATION
doc/book/addressing.rst aa63dbe63c8fc3b5e5608f0f600ef4beda51afd4
doc/book/amqp-mapping.adoc PRE-CREATION
doc/book/amqp-mapping.rst 465acd9f9949bef8a93f3d489a1084d864339dd5
doc/book/auto_links.adoc PRE-CREATION
doc/book/auto_links.rst 822cbdd7714b5ada6cf030f46d7a82ddcd30dcde
doc/book/basic_usage.adoc PRE-CREATION
doc/book/basic_usage.rst 232991a89ad21c6577c0e812706803435c41d6b6
doc/book/book.adoc PRE-CREATION
doc/book/book.rst f333001264266b2aec7da6d5218494908bb1a504
doc/book/client_compatibility.adoc PRE-CREATION
doc/book/client_compatibility.rst 6b0150fb0616de5d51fed043a9d1f2957c8daa96
doc/book/console.rst e2a13675281e739ef9f5b8e67ca3804c2548a6fd
doc/book/console_installation.adoc PRE-CREATION
doc/book/console_installation.rst 6484d0525cda159ea323bc11cee7430116d6e758
doc/book/console_operation.adoc PRE-CREATION
doc/book/console_operation.rst 1d382b5daad5b3934f66bacebc5e44dfd2627dad
doc/book/console_overview.adoc PRE-CREATION
doc/book/console_overview.rst 86445552e086f503b29bea6ce38726125426eac8
doc/book/default_config.adoc PRE-CREATION
doc/book/default_config.rst 374d69e6f2b7309220b8e9e5959c6c768d29929a
doc/book/introduction.rst 5e532ab09ca34e0655109c60e872051b2b662260
doc/book/link_routing.adoc PRE-CREATION
doc/book/link_routing.rst f9a023ebcffb227f71d2a68f1270bd6abfd2cada
doc/book/schema_rst.py 5120766eb85f5381d0279b057a2a505a5d1b6198
doc/book/technical_details.rst bce80a47ebaf1bbfff2dfe9cc135bc7b82df9903
doc/book/tools.adoc PRE-CREATION
doc/book/tools.rst a31757f6bba875bc8cddc0991a769276f4f926d2
doc/book/using.rst 474758d1a139e7bdb5fe470f5da192ade1039b61
doc/conf.py.in 43c1037a16827fbdfc913b0255fe2a9da6c02bcd
doc/index.adoc PRE-CREATION
doc/index.rst 0e00953047631ec9763bc5f9d23f50852e36ab10
doc/man/help2rst.py 98feea436e5a90590a55a894afa48bfe9a6c0e2f
doc/man/qdmanage.8.adoc PRE-CREATION
doc/man/qdmanage.rst.in c23302d58c35ac2187e33d001192752d726cdac3
doc/man/qdrouterd.8.adoc PRE-CREATION
doc/man/qdrouterd.rst.in 32741cef7d8ff2a66924045cfb1c9f464e7e2df6
doc/man/qdrouterd_conf_man.py 25302aef30c059116bf7674a10fc9d28a22e00a0
doc/man/qdstat.8.adoc PRE-CREATION
doc/man/qdstat.rst 935642c7a1c867df427611dcaa794301d9f16531
doc/notes/code-conventions.rst 21fcf0685b744b553abf7c00c8689713ff32c5f7
doc/notes/code-conventions.txt PRE-CREATION
doc/themes/bare/layout.html 113cf1a4b00ca1d7d7125841d1172513ca3ebb81
doc/themes/bare/theme.conf 2b3c705f4eed6a6096ccb1f00006336f31d97200
python/qpid_dispatch/management/qdrouter.json 197ec97f8f7332fad7350f9bf0ef06dc431a43bd
python/qpid_dispatch_internal/management/schema_doc.py 36c3faf7b1361f347b6b7b81f1efb33e6bbb0610
Diff: https://reviews.apache.org/r/49031/diff/
Testing
-------
manual review of docs.
Thanks,
Alan Conway