Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Bad interaction between _odoc_supports directory and github pages / jekyll #7364

Closed
hhugo opened this issue Mar 21, 2023 · 6 comments · Fixed by #7588
Closed

Bad interaction between _odoc_supports directory and github pages / jekyll #7364

hhugo opened this issue Mar 21, 2023 · 6 comments · Fixed by #7588
Labels
odoc
Milestone
3.8.0

Comments

@hhugo
Copy link
Collaborator

hhugo commented Mar 21, 2023

On http://ocsigen.org/js_of_ocaml/5.1.0/api/index.html, odoc.css is not found. Yet, it is available in https://github.com/ocsigen/js_of_ocaml/blob/gh-pages/5.1.0/api/_odoc_support/odoc.css.

After searching more, it could be an issue with github pages and directories with leading underscores.

Originally posted by @hhugo in #6913 (comment)
@Alizter Alizter changed the title Bad interaction between _odoc_supports directory and github pages / jelyll Bad interaction between _odoc_supports directory and github pages / jekyll Mar 21, 2023
@Alizter Alizter added the odoc label Mar 22, 2023
@hhugo hhugo mentioned this issue Mar 22, 2023
Closed
@yawaramin
Copy link
Contributor

Any reason the _odoc_support directory can't be called something like one of the popular names for these kinds of directories, e.g. static, assets, or similar?

@Alizter Alizter added this to the 3.8.0 milestone Apr 19, 2023
@Alizter
Copy link
Collaborator

Alizter commented Apr 19, 2023 •
edited
Loading

Suggesting .nojekyll is a workaround but I don't think it is satisfactory. Would a better solution be to rename the directory to something without underscores? Renaming it something like assets might be a poor choice since such a directory might exist in the build. IINM we are creating a directory target so we can't have unrelated overlap.

Perhaps removing the underscore would be sufficient. Cc @emillon ive marked this for 3.8 as I think it will be important for users to not be bitten by this.

@emillon
Copy link
Collaborator

emillon commented Apr 19, 2023

Yes, good call on fixing that for 3.8. Renaming the _odoc directory sounds good to me.

@dbuenzli
Copy link

Any reason the _odoc_support directory can't be called something like one of the popular names for these kinds of directories, e.g. static, assets, or similar?

Because if your are developing a webapp you are extremely likely to have a module that is named that way. _odoc_support is out of the module and .mld page namespace.

@dbuenzli dbuenzli mentioned this issue Apr 19, 2023
Closed
@emillon
Copy link
Collaborator

emillon commented Apr 19, 2023

I'd like to have a solution that works out of the box for github-pages users.

We have several options here:

  1. change the directory name to something that does not start with _
  2. generate an empty .nojekyll file
  3. make the directory name configurable

1 is best but as @dbuenzli explained we want to find something that can not collide with generated links. What kind of links can odoc generate? Can we move this one folder up maybe? Would starting with a dot work?

I'm not found of 2 since it's unnecessary for many users. Technically dune has access to whether the user uses github for hosting (through (source) and doc) but it seems too clever.

I'd like to avoid 3 since it's going to be too difficult to discover: a user that discovers the issue is the name of the support folder can just create a .nojekyll file instead.

@yawaramin
Copy link
Contributor

if your are developing a webapp you are extremely likely to have a module that is named that way

OK, fair enough.

Starting with a number would also work, right? E.g. 0doc_support. That can't clash with a module name.

@emillon emillon mentioned this issue Apr 20, 2023
Merged
emillon added a commit to emillon/dune that referenced this issue Apr 20, 2023
@emillon
odoc: put odoc support files in .odoc_support
07d43ad 
Fixes ocaml#7364

If the directory is named `_odoc_support` with a leading underscore, it
is omitted when deploying to github pages. This is because this system
also support the jekyll site generator, which uses this convention for
data files.

We can not use any directory name here since we want to avoid conflicts
with OCaml identifiers and names of `*.mld` files. Starting with a dot
seems to fit the requirements.

Signed-off-by: Etienne Millon <[email protected]>
emillon added a commit to emillon/dune that referenced this issue May 2, 2023
@emillon
odoc: put odoc support files in odoc.support
7995560 
Fixes ocaml#7364

If the directory is named `_odoc_support` with a leading underscore, it
is omitted when deploying to github pages. This is because this system
also support the jekyll site generator, which uses this convention for
data files.

We can not use any directory name here since we want to avoid conflicts
with OCaml identifiers and names of `*.mld` files.

Signed-off-by: Etienne Millon <[email protected]>
emillon added a commit that referenced this issue May 3, 2023
@emillon
odoc: put odoc support files in odoc.support (#7588)
f97fc32 
Fixes #7364

If the directory is named `_odoc_support` with a leading underscore, it
is omitted when deploying to github pages. This is because this system
also support the jekyll site generator, which uses this convention for
data files.

We can not use any directory name here since we want to avoid conflicts
with OCaml identifiers and names of `*.mld` files.

Signed-off-by: Etienne Millon <[email protected]>
@emillon emillon mentioned this issue May 3, 2023
Closed
emillon added a commit to emillon/opam-repository that referenced this issue May 3, 2023
@emillon
[new release] dune (15 packages) (3.8.0~alpha2)
4d05b56 
CHANGES:

- Correctly set `MANPATH` in `dune exec`. Previously, we would use the `bin/`
  directory of the context. (ocaml/dune#7655, @rgrinberg)

- Allow overriding the `ocaml` binary with findlib configuration (ocaml/dune#7648,
  @rgrinberg)

- Modules that were declared in `(modules_without_implementation)`,
  `(private_modules)` or `(virtual_modules)` but not declared in `(modules)`
  will cause Dune to emit a warning which will become an error in 3.9. (ocaml/dune#7608,
  fixes ocaml/dune#7026, @Alizter)

- Dune can now detect Coq theories from outside the workspace. This allows for
  composition with installed theories (not necessarily installed with Dune).
  (ocaml/dune#7047, @Alizter, @ejgallego)

- Fix regression where Merlin was unable to handle filenames with uppercase
  letters under Windows. (ocaml/dune#7577, @nojb)

- On nix+macos, pass `-f` to the codesign hook to avoid errors when the binary
  is already signed (ocaml/dune#7183, fixes ocaml/dune#6265, @greedy)

- Fix bug where RPC clients built with dune-rpc-lwt would crash when closing
  their connection to the server (ocaml/dune#7581, @gridbugs)

- Introduce mdx stanza 0.4 requiring mdx >= 2.3.0 which updates the default
  list of files to include `*.mld` files (ocaml/dune#7582, @Leonidas-from-XIV)

- Fix RPC server on Windows (used for OCaml-LSP). (ocaml/dune#7666, @nojb)

- In `(executable)`, `(public_name -)` is now equivalent to no `(public_name)`.
  This is consistent with how `(executables)` handles this field.
  (ocaml/dune#7576 , fixes ocaml/dune#5852, @emillon)

- Change directory of odoc assets to `odoc.support` (was `_odoc_support`) so
  that it works with Github Pages out of the box. (ocaml/dune#7588, fixes ocaml/dune#7364,
  @emillon)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
odoc
Projects
None yet
Milestone
3.8.0
5 participants
@yawaramin @dbuenzli @emillon @hhugo @Alizter