Markdown on demand #829
Merged
Markdown on demand #829
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The markdown files in the repository are now all "source" e.g. containing ascii art rather than references to Ditaa-generated images. Specifically this change overwrites the ".md" files with their ".src.md" versions and removes the ".png" image files. This stuff can all be built on demand instead of stored in the repo.
The documentation build infrastructure now expects to preprocess every markdown file and write the result into obj/. This replaces the previous behavior of expecting the files in the repository to already be preprocessed.
Build the manual in the obj/doc/ directory (for build objects) rather than the doc/ directory (for sources). Fix the Makefile dependencies to work. They are still ugly though...
eugeneia
added a commit
to eugeneia/snabb
that referenced
this pull request
Mar 17, 2016
# Conflicts: # src/Makefile
eugeneia
added a commit
to eugeneia/snabb
that referenced
this pull request
Mar 17, 2016
| @@ -184,20 +183,20 @@ obj/jit_vmprof.o: extra/vmprof.c | $(OBJDIR) | |||
|
|
|||
| book: doc/snabbswitch.pdf doc/snabbswitch.html doc/snabbswitch.epub | |||
|
|
|||
| doc/snabbswitch.md: markdown Makefile doc/genbook.sh | |||
| obj/doc/snabbswitch.markdown: snabb markdown Makefile doc/genbook.sh | |||
There was a problem hiding this comment.
@lukego Why does snabbswitch.markdown require snabb though?
lukego
added a commit
to lukego/snabb
that referenced
this pull request
Mar 18, 2016
Resolved a bunch of conflicts because I edited the markdown files pdf-manual and then replaced .md with .src.md files on markdown-on-demand.
Previously process-markdown took only an input file argument and printed the result to standard output. Now it takes both an input file and output file argument. The important change is that the '.images' directory containing ditaa images is now created in the same directory as the output file, and that directory is created if necessary. Previously the '.images' was created in the source directory and in practice this was only the right thing if the output file happened to also be in that directory. This was true the past when we were converting foo.src.md -> foo.md but is not true anymore now that we convert foo.md -> obj/foo.md. src/Makefile is updated to reflect this. This also made it possible to drop the Makefile dependency from the manual on the 'snabb' executable, which was an ugly hack intended to ensure that the required directory tree in obj/ had been created somehow. Now the process-markdown script automatically creates any required output directory.
eugeneia
added a commit
to eugeneia/snabb
that referenced
this pull request
Mar 18, 2016
| @@ -153,7 +153,7 @@ $(JITOBJS): obj/jit_%.o: ../lib/luajit/src/jit/%.lua $(OBJDIR) | |||
|
|
|||
| $(RMOBJS): obj/%: % | |||
| $(E) "MARKDOWN $@" | |||
| $(Q) scripts/process-markdown $< > $@ | |||
| $(Q) scripts/process-markdown $< $@ | |||
There was a problem hiding this comment.
@lukego This might have broken things? It worked before but now I get:
MARKDOWN obj/program/lwaftr/doc/README.ndp.md
make: *** [obj/program/lwaftr/doc/README.ndp.md] Error 1
Had used 'readlink -f' to canonicalize input and output paths. However, this fails when the output directory does not exist yet. Now uses 'readlink -m' instead to avoid this problem.
lukego
added a commit
to lukego/snabb
that referenced
this pull request
Mar 21, 2016
This file now contains a diagram so it needs to have separate .src.md and .md versions. This can be cleaned up when these changes eventually merge with the on-demand markdown (snabbco#829).
eugeneia
added a commit
to eugeneia/snabb
that referenced
this pull request
Mar 21, 2016
eugeneia
added a commit
to eugeneia/snabb
that referenced
this pull request
Mar 21, 2016
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This branch creates all documentation build products on-demand instead of expecting them to be checked into the repository. This simplifies the source code maintenance.
ditaaare now created byMakefileand not stored in the repository..src.mdconcept is gone. Now all markdown files are in "source" format, with ascii art, and the Makefile preprocesses them all while building the manual.The manuals also now build in
obj/doc/instead of directly indoc/.The benefit that I see here is simplicity for maintaining the sources. Now developers updating documentation don't have to remember to
make markdownand decide which parts of its output are relevant to check in. I also like the fact that relatively exotic build dependencies likeditaawould only be needed for building the manual and not for routine development.The main downside is that the docs will not show pretty pictures when you browse them on the Github web interface. Bummer. I don't feel we can afford this level of complexity for nice-to-have features of secondary documentation formats though.