1.. _rfc-74: 2 3=========================================================== 4RFC 74: Migrate gdal.org to RTD-style Sphinx infrastructure 5=========================================================== 6 7======== ============== 8Author: Howard Butler 9======== ============== 10Contact: howard@hobu.co 11Started: 2019-May-19 12Status: *Adopted* 13======== ============== 14 15Summary 16------- 17 18The document proposes migrating the GDAL documentation from a Doxygen to 19`Sphinx <http://www.sphinx-doc.org/en/master/>`__ in 20`ReadTheDocs <https://readthedocs.org>`__ format. 21 22Motivation 23---------- 24 25Casual contribution to the GDAL documentation is challenging. Wiki-style 26contribution is possible through the Trac instance, but that requires 27getting an OSGeo login, which is a high bar, and the Trac information is 28disconnected from the primary documentation. Other projects such as PROJ 29and `MapServer <https://mapserver.org>`__ have seen significant uptick 30in contributed documentation by adopting Sphinx-based systems, and we 31hope the adoption of this approach for GDAL will ignite a renaissance of 32documentation contribution as it did for those projects. 33 34The current approach has some significant deficiencies that have not 35been overcome by waiting for new versions of Doxygen to arrive. These 36include: 37 38- The Doxygen build buries the source of the documentation deep into 39 the source tree, which makes it hard to find where to properly add 40 information. 41- The structure of the website is indirect from the source code that 42 creates it. 43- New features such as convenient mobile-friendly styling, alternative 44 serializations such as PDF, and tighter API and user-level 45 documentation integration are not within easy reach. 46- Editing of raw HTML means that convenient output of other 47 serialization types, such as PDF, Windows Compiled Help, or manpage 48 output is challenging. 49 50Proposal 51-------- 52 53The GDAL team will refactor the GDAL.org website to be based on Sphinx 54with the following properties: 55 56- Convert the bulk of the existing documentation to reStructuredText 57- Adapt the `ReadTheDocs 58 theme <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__ 59- Apply an "Edit this Page on GitHub" link to every page on the site 60 for convenient contribution 61- Utilize `GitHub Pages <https://pages.github.com/>`__ to host 62 gdal.org, with updates being regenerated and committed to a 63 repository by `Azure 64 Pipelines <https://dev.azure.com/osgeo/gdal/_build>`__ continuous 65 integration. 66- Output a PDF serialization of the website for documentation version 67 posterity. 68 69Considerations 70~~~~~~~~~~~~~~ 71 72- Numerous hard links to driver pages exist in source code. Care must 73 be taken to attempt to preserve these links as well as possible with 74 redirects to adapt to any new organization. 75- Porting of existing Trac content to the new data structure will allow 76 decommission of that piece of infrastructure. Significant content 77 porting investment may be required to achieve this. 78- Doxygen API-style documents are still valuable, and we propose to 79 keep a rendering of them at ``/doxygen`` for users who wish to 80 continue with that approach. Internal API documentation will continue 81 to use Doxygen, and it will be reflected into the Sphinx website 82 using the Breathe capability. 83- Initial content organization will attempt to mimic the existing 84 website as well as can be achieved, but no requirement to maintain 85 adherence to the previous structure is required if other organization 86 approaches are more convenient given the features and capabilities of 87 Sphinx. 88- Existing translations will not be ported. Adaptation and continuation 89 of porting of translations is beyond the scope of this RFC, but there 90 are capabilities for managing translations in Sphinx (MapServer.org 91 provides an excellent example), and follow-on contributors can keep 92 moving forward with the architecture once the initial effort is 93 complete. 94- Content may be missed during the transition. Please file tickets in 95 GitHub for any items that became more difficult to find or are gone 96 after the transition. 97 98Logistics 99~~~~~~~~~ 100 101A current example of the site lives at 102`https://gdal.dev <https://gdal.dev>`__ This example is set to noindex. 103Once the RFC is passed, adaptation of the infrastructure that builds it 104will be migrated to `https://gdal.org <https://gdal.org>`__ and the 105example website will be completely decommissioned. Currently, 106`https://github.com/hobu/gdal <https://github.com/hobu/gdal>`__ 107``doc-sprint`` branch is the fork that drives this content. It will be 108squash-merged to the main repository at the passing of the RFC. 109 110References: 111 112- `issue #1204 <https://github.com/OSGeo/gdal/issues/1204>`__. 113- `2019 OSGeo Community Code 114 Sprint <https://wiki.osgeo.org/wiki/OSGeo_Community_Sprint_2019>`__ 115 116Voting history 117-------------- 118 119+1 from KurtS, HowardB, DanielM, NormanB, JukkaR and EvenR. 120