py for windows and custom head

[danmrc]

Hi guys,

I am not sure if this is the right way to do it, so my apologies if I am wrong.

I made 2 modifications in the package that may be interesting:

1. On windows, I can only run python via py -3, so every time I built the package it said that python was not installed. I simply added a try for py -3 on build.jl. It works here, and might solve this for some windows users (although this is not something that prevents people using the package, it might be handy and was really simple). I kept the python3 because I guess this is how unix/osx calls python3. I think it might work in those systems, but I haven't tried it.

2. Another change is on the serve() command: I added an option for a custom head.html. To understand why this is useful, it is not straight forward to generate a webpage for a repo - only for the user. I am using this package to write a small guide for economists using Julia (in portuguese, which is my native language and is far from complete). It took me a couple of hours to understand exactly what I had to change in order to this work, but I did.

To make it work, the biggest problem was with head.html so it would get the files from the right address. Here is the modified head. However, this generated another problem: I could not serve it and take a look at the site, since the head.html was written to point to the right paths in github.

My solution was to create two head files, one for serving and one for publishing. Since I am publishing inside a docs folder in github, I don't use publish() . Therefore, I changed serve(). I have tested it and it works, but I have not tested in another OS.

I hope this can be useful for the package

Best regards

[tlienart]

Hello Daniel! thanks so much for helping out, testing on windows 10 is something I was not able to do so it's super helpful to have someone who is willing to try things out and report problems.

Now I have a comments/questions for your suggestions

suggestion 1 -- python 3

I understand your issue though you would also need to change where it's called (in the optimize function). But I'm not sure that's an ideal way to do it because other people on other systems might have yet different ways of calling python themselves. (Is py -3 the standard way on Windows?).

I think the easiest would be to follow the good example specified by the package PyCall https://github.com/JuliaPy/PyCall.jl where you can specify whatever path you want to the python3 executable. I've openened an issue for this (#160) and will try to do this soon.

suggestion 2 -- head

I'm not entirely sure I understand what you're trying to do here 🙂 you can modify the head.html by changing src/_html_parts/head as indicated in the folder structure section. You can also see a simple step-by-step way of modifying / creating your own layout by looking at this tutorial

If that doesn't help, could you show me the repository where you're trying to use this and I can take a look and make suggestions depending on what you want to do? That will also help me understand how to clarify things better in the doc.

Thanks!

[danmrc]

1. Python

It looks like it is the standard way on windows. I am not a big python user but the documentation hints that this is the way.

"But I'm not sure that's an ideal way to do it because other people on other systems might have yet different ways of calling python themselves."

That is why I kept the python3 option. I can test it to see if it works on osx. Maybe it could be done in a way that if Sys.iswindows() is true then it uses py -3?

" you would also need to change where it's called (in the optimize function)"

That is a good point, but since I couldn't use optimize before because JuDoc could not find python.

2. Head

I just realized that calling it "custom head" was not the best name choice. My point is, if you keep the way the head.html comes, you can only use it as a user site. You can't use it as a project site. In other words, I could use JuDoc to make the site for https://danmrc.github.io, but not for https://danmrc.github.io/repo (where repo is the name of the repository). The section for hosting the website at the documentation of the package leads to github tutorial on how to establish a user site.

However, it is straightforward to change the head.html in a way that you can host your site on a /repo address. All you need is to change some links on head. Let me use the example from the template tutorial:

<div class="menu-item"><a href="/pub/menu1.html">Menu 1</a></div>
 <div class="menu-item"><a href="/pub/menu2.html">Menu 2</a></div>
 <div class="menu-item"><a href="/pub/menu3.html">Menu `3</a></div>

The way to allow github pages to make it work is to change the /pub to /repo:

<div class="menu-item"><a href="/repo/menu1.html">Menu 1</a></div>
 <div class="menu-item"><a href="/repo/menu2.html">Menu 2</a></div>
 <div class="menu-item"><a href="/repo/menu3.html">Menu `3</a></div>

(You will also need to change the path to the css accordingly)

However, now when I use serve() to check the progress, all links are broken, since there is no path called repo on the system. One way around this is to mess with the folder pub name (I guess, I haven't tried), but then this would require to mess with the folder where serve saves the files. I didn't try that. What I did was to create another head file that serves uses when I want to serve the site in my computer (which is called head_local.html). When I want to serve the site to github, I change which head.html the serve command should use.

There might be an easier way to do this using your package and my suggestion might be absolutely useless. However, this was based on the help for the publish() command:

This is a simple wrapper doing a git commit and git push without much fanciness. It assumes the current directory is a git folder. This will work in most simple scenarios (e.g. there's only one person updating the website). In other scenarios you should probably do this manually.

But the current directory is not the directory I am using to put the site on the web, and even if it was, I could not make it work for https://danmrc.github.io/repo. So my solution was to change the head.html.

Then again, I am not sure this is the best way to do this nor if this is already implemented. Maybe this is a completely unnecessary change.

Best regards

[tlienart]

Ok right, I now understand both issues, thanks. I've opened new issues to track this:

• The first one is now Python and node call, follow PyCall's example #160
• The second one is Paths specification for project site #162

I'll try to fix both soon!

[tlienart]

Ok, I've now merged a PR for the first problem (python on windows, #160). It would be great if you could try the following (assuming you have both node and python on your computer)

pkg> add JuDoc#master

julia> using JuDoc
julia> newsite("testpy")
julia> optimize()

This should work, if you check the website, the html should be minified and there should be no javascript. If you could confirm that's the case, it would be super useful, thanks!!

Note: I've also allowed user-specification of how to call python/node via

julia> ENV["PYTHON3"] = "..." # by default `py -3` on windows now
julia> ENV["PIP3"] = "..." # by default `py -3 -m pip` on windows now
julia> ENV["NODE"] = "..." # by default `node` on windows

[tlienart]

The second problem is fixed by #165. Example: https://tlienart.github.io/testproj/.

You can already use this on master and specify in your config.md:

@def prepath = "repo"

when using optimize or publish, this will replace all paths pre-pending them with /repo/ so that for instance /pub/menu1.html will become /repo/pub/menu1.html (see the example above).

You can either specify that in the config (which is probably the most natural) or specify it when you call optimize or publish:

• optimize(...; prepath="repo")
• or publish(...; prepath="repo")

irrelevant of whether you use minify or prerender.

I hope this helps! your feedback would be much appreciated.