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

Generated index.html page ignoring custom template #348

Closed
zaino opened this issue Feb 11, 2022 · 3 comments
Closed

Generated index.html page ignoring custom template #348

zaino opened this issue Feb 11, 2022 · 3 comments
Labels
bug

Comments

@zaino
Copy link

zaino commented Feb 11, 2022 •
edited
Loading

Hi all,
hopefully I'm not just missing something obvious.

I have a custom template for the index page, but with version 9.0.1 the generated html page just redirects to myproject.html.

Folder structure:

myproject/
|-- myproject/
|   |-- __init__.py
|   |-- mymodule.py
|-- docs/
|   |-- templates/
|   |    |-- index.html.jinja2
|   |    |-- module.html.jinja2
|-- setup.py
|-- README

I'm running pdoc -t docs\templates -o docs --math myproject from the top-most myproject folder.
This generates an index.html like so:

<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <meta http-equiv="refresh" content="0; url=./myproject.html" />
</head>
</html>

This happens with 9.0.0 as well, but does not happen with 8.3.0. Unfortunately I need >=9.0.0 because my index template uses the all_modules hook I requested and obtained in a matter of hours thanks to the superstar @mhils :)

Any advice on either something I'm doing wrong or figuring out what the issue is?

Thanks in advance!
@zaino zaino added the bug label Feb 11, 2022
@zaino
Copy link
Author

zaino commented Feb 11, 2022 •
edited
Loading

Just saw the change in the changelog, sorry for not checking before posting.

Reading through issue #318 I see your proposed workaround, but before I close this, I was wondering if there's another way to have a custom, fancy intro page to the rest of the auto-generated documentation.
I think it's reasonable to have an index page where you can have sections like:

  • Intro
  • Installation
  • etc

So I'm not a fan of the change, since my answer to the useless index page was to customize it, and now I have to work around that.

Let me know what you think.

@mhils
Copy link
Member

mhils commented Feb 11, 2022

@zaino: Thanks for the useful feedback! I absolutely agree that an index page is good. There are a couple of ways to do that with 9.0.1:

1. Use myproject/__init__.py as the index

I'm actually curious, what are the contents of your myproject documentation page at the moment? The way I do it for pdoc itself is that the index page lives right in there:

If you don't like to have all that in a docstring, you can also use an external Markdown file. The only downside is that included files won't live-reload with pdoc's builtin web server. Directly writing HTML instead of Markdown works as well.

2a. Use a hidden module to force index generation

That's the workaround described in #318 (comment):

pdoc [your module] _json

allows you to force an index without modifying any templates.

2b. Force index page generation in the template

Instead of using the somewhat ugly _json hack, you can also force the index template to render like so:

{% set root_module_name = "" %}
{% extends "default/index.html.jinja2" %}

With one of the next releases (once I find some time for #346) you will also be able to simplify it to {% extends "default/frame.html.jinja2" %} in index.html.jinja2, which would then completely bypass the root_module_name logic in default/index.html.jinja2.

@zaino
Copy link
Author

zaino commented Feb 11, 2022

Thanks @mhils, 2a works, and that's what I'm gonna use.

Extending index.html.jinja2 directly with the default frame.html.jinja2 is a good workflow, I actually wanted to ask for that :)

All good on my end, I'll close this issue and look forward to next releases!

Thanks again for the prompt support.

@zaino zaino closed this as completed Feb 11, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@zaino @mhils