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