Hello, and thank you for the feedback :)

Using the pelican toc_extract plugin works really well to display the Table Of Contents on each page.
Following Adi's advice I also added a Jinja filter in pelicanconf.py to display prev and next page (sorted by page title at the moment).
So far, the pages layout is flat: all pages are at the root of the githubpages /pages directory.

However, when converting trac pages to pelican, I realized that many tags are actually sphinx tags and not "pure" rst:

- :doc: links are easy to convert to {filename} pelican links
- :download: links for examples files can probably be replaced by {static} pelican links (#TODO)
- :py:class|meth|func: however are used to link to the api doc, and I have no idea how to implement this

Also, the index.rst files are essential to navigate the pages through the toctree directive, but this directive seems to be sphinx only.

So I'm wondering if we'll have to migrate each rst file to a proper pelican file, and if yes, what would be the best way to achieve it?
Ideally, we'd have to:
- replace all sphinx tags, especially the API ones
- find a way to create a "content map", to replace the toctree elements. Maybe through a page custom attribute and a global conf object? This would also be useful for the prev/next elements on each page.

Sources: https://github.com/JudgeGregg/pelitwi ("transform" branch)
- script.py is used to convert the trac rst.txt files to pelican edible .rst files
- copy_and_clean.sh puts the transformed files in the content/pages directory and generates pelican output

Please let me know what you think :)

Grégoire Juge

Le mer. 18 août 2021 à 20:24, Adi Roiban <adiroiban@gmail.com> a écrit :
On Wed, 18 Aug 2021 at 10:46, Grégoire JUGE <gregoire.juge@gmail.com> wrote:
> Hello,
> I tried to replicate the current https://twistedmatrix.com/documents/current/index.html theme with pelican:
> https://judgegregg.github.io/pelitwi/ (I reused Moshe Z.'s example to make comparison easier :) )
> Sources: https://github.com/JudgeGregg/pelitwi
> Pros:
> - Creating a theme from scratch seems easy at least for the basics
> - Pelican handles rst natively, so porting current pages should be doable without too much hassle
> Cons:
> - The theme feels a bit dated maybe (but switching/upgrading theme looks simple)?
> - Pelican can be used to host any static content (not only blogs) but it requires a little more work AFAIK
> - I have no idea how to replicate navbar and menus on pelican (probably related to n.2)
> Please let me know what you think. If in the end we switch to Sphinx, I'd be happy to lend a hand too :)
> (Although I'm currently logged in the Twisted Libera Chat, I won't be able to use it for another week or so.)
> --
> Grégoire Juge

Thanks for your work.

I like Pelican... I see it as a simplified Sphinx alternative and at
the same time a flexible alternative.

With Pelican you can have different templates for different pages.

I am using it for my company to create the main "business page" and it works ok.
You can create side-menus in pelican for sub-pages... I am doing that
using a jinja filter
that takes as input all the pages and outputs list items.
I can share the filters.
I have various such filters...for example a similar one to generate
the footer mini-sitemap

For my site, the main (top) navbar is fixed and sourced from the
pelican conf file.

I am familiar with Jinja and RST and copy/pasting an already existing
HTML/CSS markup.
I am not good at creating new HTML and CSS. I am lucky with Boostrap CSS :)

I  guess that we can go with Pelican + GitHub pages for the main site.
Adi Roiban
Twisted mailing list -- twisted@python.org
To unsubscribe send an email to twisted-leave@python.org
Message archived at https://mail.python.org/archives/list/twisted@python.org/message/52A7FAYRPADSOU5UC3Y3XGCWOWO2HKXD/
Code of Conduct: https://twisted.org/conduct