Embed source code into generated documentation. #2439
Merged
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
…there is markdown code in source code.
|
Looks good with the current theme (which still needs some minor tweaking). As it is available on pypi, https://pypi.python.org/pypi/mkdocs-ponylang i think it is ok to switch the theme in the |
mfelsche
previously approved these changes
Jan 26, 2018
mfelsche
reviewed
Jan 27, 2018
src/libponyc/pass/docgen.c
Outdated
| @@ -796,6 +985,8 @@ static void doc_entity(docgen_t* docgen, docgen_opt_t* docgen_opt, ast_t* ast) | |||
|
|
|||
| // Now we can write the actual documentation for the entity | |||
| fprintf(docgen->type_file, "# %s", name); | |||
| add_source_code_link(docgen, ast); | |||
There was a problem hiding this comment.
this source code link should appear after adding the type params after line 991
mfelsche
reviewed
Jan 27, 2018
src/libponyc/pass/docgen.c
Outdated
| if (doc_source != NULL) { | ||
| fprintf( | ||
| docgen->type_file, | ||
| "<div class=\"source-link\">[[Source]](%s#L%zd)</div>", |
There was a problem hiding this comment.
please put this div on a new line, otherwise it appears as part of the heading. i will style it to go right after the heading (possibly on the same line if there is enough space).
mfelsche
approved these changes
Jan 30, 2018
|
Approved. You can see embed source code listings and the new theme in use here: https://mfelsche.github.io/ponycheck/ |
|
This is super nice. |
|
The only thing that is missing is to change this line to install https://github.com/ponylang/ponyc/blob/master/.travis_commands.bash#L23 |
EpicEric
reviewed
Feb 1, 2018
.travis_commands.bash
Outdated
| echo "Installing mkdocs..." | ||
| sudo -H pip install mkdocs | ||
| echo "Installing mkdocs and offical theme..." | ||
| sudo -H pip install ponylang-mkdocs |
There was a problem hiding this comment.
This command errors out. Shouldn't the package be mkdocs-ponylang?
There was a problem hiding this comment.
You are right. Will fix that ASAP.
|
I'm doin' it! |
mfelsche
added
the
changelog - added
ponylang-main
added a commit
that referenced
this pull request
Feb 4, 2018
dipinhora
pushed a commit
to dipinhora/ponyc
that referenced
this pull request
Jun 5, 2018
* add js and css file for docs at build time * avoid warning for docs contents and start to list source files into mkdocs.yml. * Get a first basic version of source embedding working. * Fix layout js and css. * Fix source read not putting at null terminator at end.. * Avoid parsing code twice. * Make bigger numbering so it handles up to 9999 lines. * Add more margin for the code so it is spaced properly with the numberings. * Escape triple back tick in markdown so it does not fail parsing when there is markdown code in source code. * Handle name clashes. * cleanup file. * Cleanup file. * Auto scroll to selected lines. * Add link to source code for methods. * Add link to sources for field and entities. * Remove border for code. * Avoid buffer overflow when reading source file. * Move path related function into paths.h * Add the trick to use multiple backtick. * Factorize code for adding source link. * Better display for source link. * remove unsued method. * Avoid leaking memory. * Put each source code in a folder with its package name. * make path more robust when embedding source code in documentation * fix merge. * copy .docs files to the generated documentation. * Add newer version of highlight.js * Fix some compile errors on Linux. * fix more compilations error on Linux. * fix one more compile error on Linux * Add comments and assert. * Embed source code into documentation * Fix a couple of issues thanks to mfelsche code review. * Add support for older browsers by adding retro-compatibility CSS property for the hidden attribute. * Fix more memory leaks in the documentation generation. * Use linked list to manage the source file included in the documentation generation. * Make link to source code fonts smaller using CSS. * Fix compilation on older GCC. * Fix duplicate entry in mkdocs.yml for source file. * Fix get_file_name modifying its argument on linux. * Remove unecessary const on result of some path functions. * Fix confusion for get_file_name which does NOT allocate a new string. * Wrap full source code file into a HTML block to process them later on. * Remove hidden attribute for the div that wrap source file. * Remove extra file that will be part of the official them. Also remove wrappre div for souce code file. * Remove no more used functions for copying extra documentation files. * Remove copy_file_content function which is no more used. * Fix few issues with markdown layout. * Use span instead of div for link to source code. * Use pony custom allocator instead of malloc/calloc/free. * Switch theme for mkdocs from readthedocs to ponylang. * install offical pony mkdocs'theme by default * Fix installation of mkdocs and custom theme in travis script.
dipinhora
pushed a commit
to dipinhora/ponyc
that referenced
this pull request
Jun 5, 2018
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 PR add support to embed source code into the generation documentation. As such it aims to fix #2291.
At that point, I got all the features I want and it works great on my computer. Yet, I introduced some platforms specific code and I only tested on Windows so far (I am not even sure it build on any Unix). So please, add the do not merge label for now, while I will try to clean this up, make sure it build on run on other platforms and hopefully add some tests. If however you want to try it now and spot any obvious mistakes or poor design, please don't hesitate to comment.