+
+
+
+
- Marine iguanas are truly splendid creatures.
-Evolution is cool.
- -
+ 
+ 
+ dot(a, a) = 14| - - - - - - - | -
- CONTENT HERE - - |
-
| - - - - - - - | -- - -``` - -and the `foot.html` should be adapted to: - -```html - - | -
` blocks - -#### Fixing spacing - -Firefox or Chrome/ium's excellent dev-tools are super helpful to fine tune stylesheets. -Here things are pretty straightforward though. - -Firstly we need to add vertical padding above `` level title: - -```css -h1 { padding-top: 2em; } -``` - -Then, let's widen the menu a little - -```css -td#layout-menu { - padding-left: 15px; - padding-right: 25px; -} -``` - -and let's reduce the padding on the left of the `jd-content` element: - -```css -.jd-content { padding-left: 5%; } -``` - -Thirdly, in the original stylesheet there is this element: - -```css -pre { - padding: 0; - margin: 0; -} -``` - -which you can just remove to have a bit more space around code blocks. - -There's probably still things that could be done to improve the layout overall (and make it more responsive!) but we'll leave it at that. - - - -### Adjusting other files - -Here we don't need to adjust anything else but you could want to adjust the pages in another context: - -* `head_highlight`, `head_katex`, `foot_highlight` and `foot_katex` are probably best left as they are, they will be appended if need be to pages (see in `head` and `foot` the `{{if hasmath}}` and `{{if hascode}}` blocks) -* `page_foot` you may want to change, it defines what goes at the bottom of the `.jd-content` div. - -By default `page_foot` looks like - -```html -
--``` - -It should be fairly straightforward to adapt that to your needs. - -## Making a PR to the theme repo - -Let's say you've built your own template and are pretty happy with the result and you'd like to share it for other users, great! thanks for being a good citizen. - -### Create a new folder - -Head to the [JuDocTemplates.jl](https://github.com/tlienart/JuDocTemplates.jl) repository and make a PR. -The key is to keep track of what you've modified and what was left as before so that the repo is not cluttered with copies of the same file. - -In the example above the following files were changed: - -* `head.html` and `foot.html`, -* `jemdoc.css` the stylesheet. - -The JuDocTemplates repository automatically fills in the gap so you just have to provide the files that have changed. -Imitate the structure corresponding to [`basic`](https://github.com/tlienart/JuDocTemplates.jl/tree/master/src/templates/basic/src): - -``` -. -└── src - ├── _css - │ └── basic.css - └── _html_parts - └── head.html -``` - -So in the case of `jemdoc`, I will create a new folder `jemdoc` in `src/templates/` with - -``` -. -└── src - ├── _css - │ └── jemdoc.css - └── _html_parts - ├── foot.html - └── head.html -``` - -### Add your template to the list - -Next, you need to indicate the new template in `JuDocTemplates.jl` by simply adding it to the `LIST_OF_TEMPLATES` constant. - -Then, you need to add a description for your template in `docs/make.jl` (please respect the alphabetical order): - -```julia -"jemdoc" => """ - jemdoc -- © {{ fill author }}. Last modified: {{ fill jd_mtime }}. Website built with JuDoc.jl. --Simple theme with a side navigation bar, no extra javascript and a simple stylesheet. (Adapted from the original Jemdoc theme.)
- """, -``` - -Lastly you need to take a screenshot of what the template looks like of size 480x480, put it in `docs/thumb` and adjust `docs/index_head.html` following the example of the other templates: - -```css -#jemdoc { - background: url("thumb/jemdoc.png"); - background-size: contain; -} -``` - -### Check that things work - -Finally, you need to check that everything works (which is the first thing I'll do when reviewing your PR). -For that: first run the file `docs/make.jl`; this will generate a website in `docs/build` then using for instance [`LiveServer.jl`](https://github.com/asprionj/LiveServer.jl), check the generated website and that the demo corresponding to your template works as expected. - -And that's it! thanks a lot! diff --git a/docs/src/man/troubleshooting.md b/docs/src/man/troubleshooting.md deleted file mode 100644 index 695565e32..000000000 --- a/docs/src/man/troubleshooting.md +++ /dev/null @@ -1,56 +0,0 @@ -# Troubleshooting - -This page is about some of the known errors you may encounter when using JuDoc and how to deal with them. -If you encounter an error that is not mentioned here, then it's probably a bug and it would be great if you could open an issue! - -* [Error on interruption](#Error-on-interruption-1) -* [IOStream error](#IOStream-error-1) - - -## Error on interruption - -You may (rarely) get an an error thrown at you when interrupting the server with `+C`, particularly when using Juno. -There are a couple of reasons this may happen, both unrelated to JuDoc. - -### Juno - -Juno (very rarely) crashes if you coincidentally press ` +C` while Juno is doing something in the background (Juno issue [#309](https://github.com/JunoLab/Juno.jl/issues/309)). - -The stacktrace you will see will seem particularly obscure, for instance: - -``` -InterruptException: -_string_n at string.jl:60 [inlined] -StringVector at iobuffer.jl:31 [inlined] -#IOBuffer#320(::Bool, ::Bool, ::Nothing, ::Bool, ::Int64, ::Int64, ::Type{Base.GenericIOBuffer{Array{UInt8,1}}}) at iobuffer.jl:114 -(...) -``` - -or - -``` -julia> "miniERROR: InterruptException: -Stacktrace: - [1] poptaskref(::Base.InvasiveLinkedListSynchronized{Task}) at ./task.jl:564 - [2] wait() at ./task.jl:591 -(...) -``` - -**Solution**: ignore the error, restart Julia. - -### Not-Juno - -The [`LiveServer.jl`](https://github.com/asprionj/LiveServer.jl) package, which handles the live-serving of the files, is based upon [`HTTP.jl`](https://github.com/asprionj/LiveServer.jl). -The latter has a fairly complex codebase with a number of asynchronous tasks and is known to sometimes crash in (somewhat) mysterious ways. - -If the stacktrace mentions `uv_write`, `uv_write_async`, `libuv` or something of the sorts, then this is it. - -Like the "Juno" case, these errors are caused when you happen to press interrupt just as the package was doing something important in the background. -This is very rare but can happen and you can safely ignore it. - -**Solution**: ignore the error, restart Julia. - - -## IOStream error - -See the comment about HTTP.jl in the [subsection above](#Not-Juno-1). diff --git a/docs/src/man/workflow.md b/docs/src/man/workflow.md deleted file mode 100644 index d0d064b7c..000000000 --- a/docs/src/man/workflow.md +++ /dev/null @@ -1,409 +0,0 @@ -# Workflow - -In this section it is assumed that you will eventually host your website on GitHub or GitLab but it shouldn't be hard to adapt to your particular case if you intend to self-host or use another service. - -**Contents**: - -* [Local editing](#Local-editing-1) - * [Folder structure](#Folder-structure-1) -* [Libraries](#Libraries-1) - * [Highlight](#Highlight-1) -* [Hosting the website](#Hosting-the-website-1) - * [Hosting the website as a project website](#Hosting-the-website-as-a-project-website-1) -* [Optimisation step](#Optimisation-step-1) -* [(git) synchronisation](#(git)-synchronisation-1) - * [Merge conflicts](#Merge-conflicts-1) -* [Using Literate.jl](#Using-Literate.jl-1) - -## Local editing - -To get started, the easiest is to use the [`newsite`](@ref) function to generate a website folder which you can then modify to your heart's content. -The command takes one mandatory argument: the name of the folder, and you can specify a template with `template=...`: - -```julia-repl -julia> newsite("Test"; template="pure-sm") -✓ Website folder generated at Test (now the current directory). -→ Use `serve()` from `JuDoc` to see the website in your browser. -``` - -```@raw html -Click here for a demo of the supported templates (opens in a new tab). -``` - -Once you have created a new site with the template of your choice and are in the corresponding folder (`newsite` will `cd` to the new folder) you can serve your website with - -```julia-repl -julia> serve() -✓ LiveServer listening on http://localhost:8000/ ... - (use CTRL+C to shut down) -``` - -and navigate in a browser to the corresponding address to see the website being rendered. - -!!! note - - If you're using the Atom editor, you may like to use the _Atom browser_ extension which allows you to have a browser in an Atom pane. - -### Folder structure - -The [`newsite`](@ref) command above generates folders and examples files following the appropriate structure, so the easiest is to start with that and modify in place. -The main folders (generated by `newsite`) are: - -``` -. -├── assets/ -├── libs/ -└── src/ -``` - -Once you run [`serve`](@ref) the first time, two additional folders are generated (`css/` and `pub/`) along with the landing page `index.html`. - -Among these folders, - -* the **main folder** is `src/` and its subfolders, this is effectively where the source for your site is, -* you should _ignore_ `css/` and `pub/` these are _generated_ and any changes you'd do there will be silently over-written whenever you modify files in `src/`; the same comment holds for `index.html`, -* the folders `assets/` and `libs/` contain _auxiliary items_ that are useful for your site: `assets/` would contain code snippets, images etc. while `libs/` would contain javascript libraries that you may need (KaTeX and highlight are in there by default). - -In the `src/` folder, the structure is: - -``` -. -├── _css -│ ├── judoc.css -│ └── ... -├── _html_parts -│ ├── foot.html -│ ├── head.html -│ └── ... -├── config.md -├── index.md -└── pages - ├── page1.md - └── ... -``` - -**Pages** - -The `index.md` will generate the site's landing page. -The `pages/page1.md` would correspond to pages on your website (you can have whatever subfolder structure you want in there, and will just have to adapt internal links appropriately). -See also the [Syntax](@ref). - -!!! note - - At any point you can write pages in HTML from scratch if you want to go beyond what JuDoc can offer; these pages will just be copied as they are. - So for instance you may prefer to write an `index.html` file instead of using the `index.md` to generate it. - You would still put it at the exact same place though (`src/index.html`) and let JuDoc copy the files at the appropriate place. - -**HTML parts** - -The files in `_html_parts/` are the building blocks that will go around the (processed) content contained in the `*.md` pages. -So the `head.html` will be inserted before, the `foot.html` after etc. -Adjusting these will help you make sure the site has the exact layout you want. -The layout can also depend on the page you're on if it uses `{{ispage path/to/page}} ... {{end}}` (see [Templating](@ref)). - -**CSS** - -The style sheets in `_css/` will help you tune the way your site looks. -The `judoc.css` is the stylesheet that corresponds more specifically to the styling of the `.jd-content` div and all that goes in it, it is usually the first style-sheet that should be loaded. -The simplest way to adjust the style easily would be to define your own stylesheet `_css/adjustments.css` and it be the last stylesheet loaded in `_html_parts/head.html` so that you can easily overwrite whatever properties you don't like and define your own. -You could also have specific stylesheet that would only be loaded on specific pages using `{{ispages ...}}` (see [Templating](@ref)). - -!!! note - - It wouldn't be hard for JuDoc to use page variables in the CSS stylesheet too. You could then do things like - ```judoc - @def col1 = aliceblue - ``` - and - ```css - .mydiv { color: $col1 } - ``` - I'm not 100% sure how useful that could be though so if you would like to see this happen, please open an issue! - -**Folder organisation** - -Auxiliary assets such as images, code snippets, pdfs etc. should ideally go in the `assets/` folder (or subfolders). -The files that are in `assets/` will not tracked for change and will also not get copied around. - -An alternative approach is to keep auxiliary assets in `src/pages/` (or subfolders). -The main advantage being that some users might find it better to structure their content with the page markdown as well as the page resources in one folder. -If you decide to do this, bear in mind that whatever is in `src/pages/` gets copied to the generated `pub/` folder during the initial website compilation. -While this will be imperceptible if you only have a few light assets, it could slow the initial pass down if you have many heavy assets; if that's the case though, you are probably better off with the first approach putting all resources in `assets/` and subfolders. - -## Libraries - -Assuming you used the [`newsite`](@ref) function to get started, you have a `libs/` folder with - -``` -. -├── highlight/ -└── katex/ -``` - -If you require other libraries to run your website, this is where you should put them while not forgetting to load them in your `_html_parts`; for instance in the default `foot_highlight.html` you will find: - -```html - - -``` - -which loads and applies `highlight.js`. - -### Highlight - -Assuming you used the [`newsite`](@ref) function to get started, you have the `libs/highlight/` folder with - -``` -. -├── github.min.css -└── highlight.pack.js -``` - -If you want to change either how things look or which languages are supported, you should head to [highlightjs.org](https://highlightjs.org/download/), select the languages you want in the **Custom package** section, download the bundle and copy over the relevant files to `libs/highlight/`. -By default, the files that are created with [`newsite`](@ref) allow highlighting for `bash`, `html/xml`, `python`, `julia`, `julia-repl`, `css`, `r`, `markdown`, `ini/TOML`, `ruby` and `yaml`. - -Just remember to refer to the appropriate style-sheet in your HTML building blocks for instance the default `src/_html_parts/head_highlight.html` contains: - -```html - -``` - -## Hosting the website - -In this section, the assumption is that you will host your website on GitHub. -The procedure should be very similar with GitLab. -If you're using your own hosting, you would pretty much just need to copy/clone the content of your folder. - -On GitHub/GitLab, the first step is to create a repository that would be acceptable for a personal webpage. - -* Follow the guide to [do so on GitHub](https://pages.github.com/#user-site). -* Or the guide to [do so on GitLab](https://about.gitlab.com/product/pages/). - -Once the repository is created, clone it on your computer, remove whatever is in it if it wasn't empty and copy over the content of the website folder (so if you had done `newsite("Test/")` then you'd copy over the content of the folder `Test` into the newly cloned folder `username.github.io/`). - -Now just do the usual `git add`, `commit` and `push` and your site will be live in a matter of minutes. - -### Gitlab users - -On Gitlab, there are two small differences: - -1. your website needs to eventually be in a `public/` directory of the repository, -1. you need to specify a CI/CD script that tells Gitlab how to deploy the site. - -Luckily both of these can be done in one shot, all you need to do is add a script as follows in your repository: - -```yaml -pages: - stage: deploy - script: - - mkdir .public - - cp -r * .public - - mv .public public - artifacts: - paths: - - public - only: - - master -``` - -The only non-trivial bit is the `script:` section: the only thing it does is tell the runner to copy all your files in a `public/` "virtual" directory. -Note that this will _not_ physically create a directory in your repo, rather it will, on Gitlab, make sure the files are located in such a way that they can be rendered. - -**Note**: if for some reason your repository is private and you would like to avoid for some files to be in the `public/` folder, then just add a couple of lines in the `script:` part removing (`rm`) the files you don't want to put there (e.g. sensitive data files). - -### Hosting the website as a project website - -You may want to host your website not as a user website on `username.github.io/` but as a project website on `username.github.io/project/`. -For this to work well, the only thing that is required is to have all links start with `/project/` instead of just `/` (the default). -JuDoc makes this easy to do this as a final step before publication. - -The best way to do it is: - -1. specify a `prepath` global variable in your `src/config.md` file by adding a line: `@def prepath = "project"`, -1. use [`optimize`](@ref) and/or [`publish`](@ref) (even if you don't do the minification or the prerendering). - -Alternatively, you can specify the `prepath` when calling `optimize` or `publish` so for instance: - -```julia-repl -julia> optimize(prerender=false, minify=false, prepath="project") -``` - -will do a pass over all generated pages and make sure all paths are prepended with `/project/`. - -## Optimisation step - -The [`optimize`](@ref) function should typically be run before you push your website online. -That step can: - -1. pre-render KaTeX and highlight code to HTML so that the pages don't have to load these javascript libraries, -1. minify all generated HTML and CSS. - -Those steps (which you can opt out of using the appropriate keyword `prerender=false` or `minify=false`) may lead to faster loading pages. - -In order to run this optimisation step, you will need some [dependencies](/#External-dependencies-1) but if you don't have them, JuDoc will tell you and ignore the corresponding step. -Note also that doing a full pass of pre-rendering and minifying may take a few seconds depending on how many pages you have. - -## (git) synchronisation - -The [`publish`](@ref) function helps you wrap the [`optimize`](@ref) step as well as a git `add`, `commit` and `push` all in one (provided the `optimize` step didn't fail). - -So, in short, your full workflow may look like - -```julia -using JuDoc -# cd to the appropriate directory -cd("path/user.github.io") -# start serving -serve() -# ... -# edit things, add pages, tune layout etc. -# while keeping an eye on the browser to check -# ... -# all looks good, stop the server with CTRL+C -^C -# and now the final step to optimize and push: -publish() -``` - -### Merge conflicts - -Since the `pub/` and `css/` and `index.html` folder are _generated_, it can sometimes cause git merge conflicts if, for instance, you have edited your website on computer A, optimised and published it and then subsequently pulled on computer B where -- say -- the content hasn't been minified yet. -This could cause messy merge conflicts that would be annoying to fix. -An easy way to reduce this risk is to simply remove the generated folders and files before pulling. - -The function [`cleanpull`](@ref) does precisely that and should be used if you intend to edit your website from multiple computers. -It simply: - -1. removes all generate folders/files from your current director, -1. pulls. - -So in such a case, your full workflow would be: - -```julia -using JuDoc -cd("path/user.github.io") -cleanpull() -serve() -# ... -publish() -``` - -## Using Literate.jl - -(_Thanks to [@cormullion](https://github.com/cormullion) for this section_) - -You can use Fredrik Ekre's [Literate.jl](https://github.com/fredrikekre/Literate.jl) package to create Markdown pages suitable for including in your JuDoc workflow. Literate.jl lets you write everything in a Julia source file, including your code, comments, tests, generated plots, and so on. When you execute the Julia file, all your code runs, and you can arrange for Literate.jl to write output such as Markdown-formatted text (and/or Jupyter notebooks) to suitable files. -Literate.jl's syntax relies on various different flavours of comment, some of which are shown in the simple example below. - -All non-Julia code has to be commented. -Markdown markup language is applied immediately after the first `# `. -You can see the `>` Markdown quote syntax and the `##` Markdown header level 2 syntax. -Lines preceded by `#jl` are not included in the Markdown output. -Lines ending with `#src` are evaluated when you run the Julia file, but are not copied into the Markdown output file. -Lines beginning with `#src` are Julia comments that don't make it as far as the Markdown file. -Refer to [Literate.jl's docs](https://fredrikekre.github.io/Literate.jl/stable/) for more information. - -You can see from the final five lines in the example that, when you run this file in Julia, the final step is to run the `Literate.markdown` function, taking the name of the Julia source file (`functionoftheweek.jl`) as input, and writing a new Markdown file to the directory `src/pages/` as `fotw_floorceil.md`. -Finally, if the JuDoc server is running, you'll find the generated HTML page as `/pub/fotw_floorceil.html`. - -````` -#jl This is a Julia source file! - -# @def title = "Function of the week: floorceil()" -# @def hascode = true - -# > To be, or not to be. That's what they reckon. - -# ## Function of the week: floorceil() - -# Welcome to another weekly post in which I present a cool Julia function that I've -# just discovered. This week it's the turn of `floorceil()`. It might sound like -# something that comes in a tin, but in fact it's a useful function in the Dates module -# that returns two Dates or DateTimes, one before, and one after, the specified time by -# a certain unit of time. - -# For example: - -using Dates - -Dates.now() - -# -# 2019-05-09T11:29:23.913 -# -#src # would be nice if the output from commands could be included! - -Dates.floorceil(now(), Dates.Month(1)) - -# -# (2019-05-01T00:00:00, 2019-06-01T00:00:00) -# - -# and you can see that the result contains the beginning and the end of the month -# that includes the present time of day. - -a, b = (Dates.floorceil(now(), Dates.Month(1))); -Dates.canonicalize(Dates.CompoundPeriod(b - a)) - -# -# 4 weeks, 3 days -# - -# That's all for today. Until next time! - -#src Lines with this tag appear only in this Julia source file. -using Literate #src -Literate.markdown("functionoftheweek.jl", #src - "src/pages/", #src - name="fotw_floorceil", #src - documenter=false) #src - -````` - -When this Julia file is executed, the resulting Markdown output will look like the listing below. -Notice that the two JuDoc `@def` lines have survived the journey from Julia to Markdown intact, and will now be actively available for the JuDoc generation process. - -````` -@def title = "Function of the week: floorceil()" -@def hascode = true - -> To be, or not to be. That's what they reckon. - -## Function of the week: floorceil() - -Welcome to another weekly post in which I present a cool Julia function that I've -just discovered. This week it's the turn of `floorceil()`. It might sound like -something that comes in a tin, but in fact it's a useful function in the Dates module -that returns two Dates or DateTimes, one before, and one after, the specified time by -a certain unit of time. - -For example: - -```julia -using Dates - -Dates.now() -``` - -2019-05-09T11:29:23.913 - -```julia -Dates.floorceil(now(), Dates.Month(1)) -``` - -(2019-05-01T00:00:00, 2019-06-01T00:00:00) - -and you can see that the result contains the beginning and the end of the month -that includes the present time of day. - -```julia -a, b = (Dates.floorceil(now(), Dates.Month(1))); -Dates.canonicalize(Dates.CompoundPeriod(b - a)) -``` - -4 weeks, 3 days - -That's all for today. Until next time! - -*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).* -`````