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

[Rodrigo Vivi]

On Tue, Oct 30, 2018 at 03:30:06PM +0200, Jani Nikula wrote:
> 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.

it makes sense.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi at intel.com>

> 
> 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
> _______________________________________________
> dim-tools mailing list
> dim-tools at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dim-tools