Documentation under Live Examples are currently generated from text based Dicts under docs/example.jl, which are later parsed as code.
Current implementation requires that individual lines of executable code be separated by newline chars and limits the ability to highlight code portions or insert explanatory comments.
Proposal is to, instead, create binary files that can also be used for visual display, as string. Binary files are not bound by above restrictions and can be leveraged to improve the visual representation of a page's code.
Proposed changed aim to improve the code base and overall example quality whilst keeping intended functionality.
Proposed improvements
Easier to format, comment and highlight code portion of the example
Better control over the visual aspect of the code inside the pre section of the pages, while keeping intended functionality of displaying both the code and the final result.
Example code no longer limited by \n characters between code lines
Individual code examples as individual files
Simplified methods docs(), under docs/make.jl
Simplified docs/examples.jl, examples are easier to find and read
Changed default .html page from components.html to index.html to leverage default behaviour of most web servers.
components.html is however still created
Replaced hard-coded href, src and link, such as https://antonioloureiro.github.io/VueJS.jl/DocsElements.html with relative paths, so that documentation can be used
Replaced hard-coded output directories, e.g. public/<file.html> with relative paths, specified under base.jl
Replaced hard-coded filesystem paths under workflow/docs.yml with github ENV variables
Easier to deploy documentation locally or across forks.
Current limitations
As previously, variable naming across different examples required to be different
Each binary under docs/examples should return a VueJS.Page
Example definitions for notebook based pages and binary examples somewhat unstandardized, see file examples.jl
Documentation under
Live Examplesare currently generated from text based Dicts underdocs/example.jl, which are later parsed as code.Current implementation requires that individual lines of executable code be separated by newline chars and limits the ability to highlight code portions or insert explanatory comments.
Proposal is to, instead, create binary files that can also be used for visual display, as string. Binary files are not bound by above restrictions and can be leveraged to improve the visual representation of a page's code.
Proposed changed aim to improve the code base and overall example quality whilst keeping intended functionality.
Proposed improvements
presection of the pages, while keeping intended functionality of displaying both the code and the final result.\ncharacters between code linesdocs(), underdocs/make.jlcomponents.htmltoindex.htmlto leverage default behaviour of most web servers.components.htmlis however still createdhttps://antonioloureiro.github.io/VueJS.jl/DocsElements.htmlwith relative paths, so that documentation can be usedpublic/<file.html>with relative paths, specified underbase.jlworkflow/docs.ymlwith github ENV variablesCurrent limitations
docs/examplesshould return a VueJS.Page