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

[Rodrigo Vivi]

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.

> 
> 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