[PATCH 03/11] doc: don't reuse README for index.rst and project home page

[Jani Nikula]

On Thu, 25 Oct 2018, Rodrigo Vivi <rodrigo.vivi at intel.com> wrote:
> On Thu, Oct 25, 2018 at 06:22:03PM +0300, Jani Nikula wrote:
>> The documentation main page and the project home page have slightly
>> different functions. At the cost of slight duplication, have different
>> texts for each.
>> 
>> Add README.rst to conf.py excludes as it's only used by gitlab.
>
> It's cool that gitlab accepts .rst for that. I was expecting a .md
>
> But what about .md anyway? So it would be clear that all .rst
> docs are compiled for the final doc and README.md is only for gitlab
> page.

I'm fine with .md for README, but I'd rather make that a separate
follow-up patch when I have the time to figure out the proper syntax for
this on gitlab, and how to try it out before actually pushing.

BR,
Jani.

>
>> 
>> Signed-off-by: Jani Nikula <jani.nikula at intel.com>
>> ---
>>  README.rst | 21 +++++++++------------
>>  conf.py    |  2 +-
>>  index.rst  | 16 +++++++++++++++-
>>  3 files changed, 25 insertions(+), 14 deletions(-)
>> 
>> diff --git a/README.rst b/README.rst
>> index 1571a23b4857..189469946130 100644
>> --- a/README.rst
>> +++ b/README.rst
>> @@ -1,19 +1,16 @@
>> -This documentation covers the tools and workflows for maintaining and
>> +DRM Maintainer Tools
>> +====================
>> +
>> +This project covers the tools and documentation for maintaining, committing, and
>>  contributing to the Linux kernel DRM subsystem's drm-misc and drm-intel
>>  repositories. The intended audience is primarily the maintainers and committers
>>  of said repositories, but the workflow documentation may be useful for anyone
>>  interested in the kernel graphics subsystem development.
>>  
>> -Both drm-misc and drm-intel are maintained using the same tools and very similar
>> -workflows. Both feed to the same testing and integration tree, the drm-tip. The
>> -documentation here is mostly shared, highlighting the differences in workflows
>> -where applicable.
>> -
>> -Please use the `dim-tools at lists.freedesktop.org`_ mailing list for
>> -contributions, bug reports, and discussion about the tooling and documentation.
>> +Please see the `DRM Maintainer Tools Documentation`_ for more information, and
>> +`contributing and contact`_ on how to collaborate on the documentation and
>> +tools.
>>  
>> -.. _dim-tools at lists.freedesktop.org: https://lists.freedesktop.org/mailman/listinfo/dim-tools
>> +.. _DRM Maintainer Tools Documentation: https://drm.pages.freedesktop.org/maintainer-tools/
>>  
>> -Visit the  `DRM Maintainer Tools
>> -Documentation <https://drm.pages.freedesktop.org/maintainer-tools/>`_ for more
>> -information on these tools.
>> +.. _contributing and contact: https://drm.pages.freedesktop.org/maintainer-tools/CONTRIBUTING.html
>> diff --git a/conf.py b/conf.py
>> index c2e1b14bf36a..c208a702910f 100644
>> --- a/conf.py
>> +++ b/conf.py
>> @@ -80,7 +80,7 @@ language = None
>>  # List of patterns, relative to source directory, that match files and
>>  # directories to ignore when looking for source files.
>>  # This patterns also effect to html_static_path and html_extra_path
>> -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
>> +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.rst']
>>  
>>  # The reST default role (used for this markup: `text`) to use for all
>>  # documents.
>> diff --git a/index.rst b/index.rst
>> index 228ca8790f59..176f75273ad0 100644
>> --- a/index.rst
>> +++ b/index.rst
>> @@ -1,7 +1,21 @@
>>  DRM Maintainer Tools
>>  ====================
>>  
>> -.. include:: README.rst
>> +This documentation covers the tools and workflows for maintaining and
>> +contributing to the Linux kernel DRM subsystem's drm-misc and drm-intel
>> +repositories. The intended audience is primarily the maintainers and committers
>> +of said repositories, but the workflow documentation may be useful for anyone
>> +interested in the kernel graphics subsystem development.
>
> I'm not sure if I liked the little duplication here, but I have no better
> suggestions.
>
> With or without changing to .md:
>
> Reviewed-by: Rodrigo Vivi <rodrigo.vivi at intel.com>
>
>> +
>> +Both drm-misc and drm-intel are maintained using the same tools and very similar
>> +workflows. Both feed to the same testing and integration tree, the drm-tip. The
>> +documentation here is mostly shared, highlighting the differences in workflows
>> +where applicable.
>> +
>> +Please see :ref:`contributing` as well as the `project home page`_ for more
>> +information on how to collaborate on the documentation and tools.
>> +
>> +.. _project home page: https://gitlab.freedesktop.org/drm/maintainer-tools/
>>  
>>  Contents:
>>  
>> -- 
>> 2.11.0
>> 
>> _______________________________________________
>> dim-tools mailing list
>> dim-tools at lists.freedesktop.org
>> https://lists.freedesktop.org/mailman/listinfo/dim-tools

-- 
Jani Nikula, Intel Open Source Graphics Center