[PATCH] D43505: [docs] Use literalinclude for most code in the Kaleidoscope tutorial to ensure the code always compiles and is up to date

[Aron Granberg via Phabricator via llvm-commits]

Voxel created this revision.
Voxel added reviewers: Wilfred, lhames.

Hi

This is my first patch submission to this list, so you'll have to tell me if I do anything wrong somewhere.

I originally submitted this to llvm-commits directly a few days ago, but I later figured out how to use Differential to submit a patch, so it seemed reasonable to resubmit it here.

The code in the kaleidoscope tutorial is currently inlined in the documentation pages and is thus never compiled to ensure it still works. Over time this code has diverged from the full code listing in small and subtle ways (such as the FunctionPassManager now being in the legacy namespace) which makes it harder for anyone following the tutorial to actually get something working.

I have replaced almost all of the code blocks in the tutorial with literalinclude blocks which include code directly from the source files based on markers. This ensures that the code in the tutorial actually compiles and is up to date, even when future changes are made and reduces the maintenance burden since changes only have to be done in a single place.

I have also uploaded a visual html diff here: https://arongranberg.com/temp/llvm-diff/
with the changed files having URLs on the format https://arongranberg.com/temp/llvm-diff/LangImpl0[1-8].html
Note that the html diff library gets a little confused when some lines have been emphasized and it may emphasize more lines than are actually emphasized or may add lots of additional spacing.

The downside of this change is that some markers are required in the source files, however they are relatively few so hopefully it is not too big of a problem.

I added as reviewers two people who seem to have done large parts of the tutorial. Hopefully that's alright.


Repository:
  rL LLVM

https://reviews.llvm.org/D43505

Files:
  docs/tutorial/LangImpl01.rst
  docs/tutorial/LangImpl02.rst
  docs/tutorial/LangImpl03.rst
  docs/tutorial/LangImpl04.rst
  docs/tutorial/LangImpl05.rst
  docs/tutorial/LangImpl06.rst
  docs/tutorial/LangImpl07.rst
  docs/tutorial/LangImpl08.rst
  examples/Kaleidoscope/Chapter2/toy.cpp
  examples/Kaleidoscope/Chapter3/toy.cpp
  examples/Kaleidoscope/Chapter4/toy.cpp
  examples/Kaleidoscope/Chapter5/toy.cpp
  examples/Kaleidoscope/Chapter6/toy.cpp
  examples/Kaleidoscope/Chapter7/toy.cpp
  examples/Kaleidoscope/Chapter8/toy.cpp

-------------- next part --------------
A non-text attachment was scrubbed...
Name: D43505.135035.patch
Type: text/x-patch
Size: 128763 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20180220/7cec9b49/attachment-0001.bin>