Make docs index more DRY

bittner commented 9 years ago

Includes content from the README file instead of duplicating it.

Notes

With my local docs generation I've seen the resulting design of the included subsection headers is different (header is underlined), although I've not seen a difference in the HTML markup compared to the other headers in the index document. Maybe you could double-check.
I've not seen a way to include also the subsection titles. This could make the code even more DRY.

mixxorz commented 9 years ago

I see it and that is.. weird. I'll look into it.

Update:

The <hr> is caused by the include expression. I wonder if there's some way to get rid of that.

Update 2:

I got it. The <hr> is caused by the ------ characters right after the Support and How to Contribute lines. It's including it directly, which generates a horizontal rule.

The workaround is to use comments as markers. In this case, I put the comments before the headers so that they will get included as well.

README.rst

.. support-marker
Support
-------

index.rst

.. include:: ../README.rst
   :start-after: .. support-marker
   :end-before: Installation

Still kinda hacky, but I don't like those <hr>s! :laughing:

bittner commented 9 years ago

Great, looks good now.

With markers the redundant sections headers are not even needed. Much better in the end.

bittner commented 9 years ago

Darn! Non-issue #14 strikes back here too! Makes the build fail for Python 2.7 + Django 1.6. :fearful:

If you merged this PR I could pull the changes into the feature branches of my other two active PRs. That requires some care in order not to lose the correct changes to the docs. (I'm traumatized by some ping-pong nightmare in the behave docs, anybody noticing?)

mixxorz / behave-django

Make docs index more DRY #26

Notes