Looks nice on desktop, and I think a simple import to sphinx makes a lot of sense. We could host this easily on docs.twisted.org It looks a bit odd on mobile, but switching theme (Furo?) is an easy toggle https://libera.ems.host/_matrix/media/r0/download/matrix.org/elBYVbawIEvwnmU...

This all sounds good to me. I’d eventually like to set up a demo.twisted.org or something as well to showcase more features interactively, but that’s for another day :-) On August 15, 2021 at 10:54:42 AM, Thomas Grainger (tagrain@gmail.com(mailto:tagrain@gmail.com)) wrote:

I'm in favour of merging the docs from twistedmatrix.com into GitHub.com/twisted/twisted

And then making general into about the twisted organisation available on twisted.org Eg stuff about ldaptor, treq, incremental, towncrier etc etc. Something with a big logo and a list of links. Maybe a hello world with an async def and task.react _______________________________________________ Twisted mailing list -- twisted@python.org To unsubscribe send an email to twisted-leave@python.org https://mail.python.org/mailman3/lists/twisted.python.org/ Message archived at https://mail.python.org/archives/list/twisted@python.org/message/3GQUIBTBEEB... Code of Conduct: https://twisted.org/conduct

Personally I'm a big fan of Pelican - I use it for my blog - and even if it's the opposite of Twisted (fully synchronous, fully offline ;-)) it's nice to be able to share Python code and open up the possibility of Python extensions for contributors. Thank you for doing this. The theme looks great. I do think we want a design refresh at some point as well, but having a robust and consistent starting point lets us get off to a much faster start with this! -g

On Aug 18, 2021, at 2:45 AM, Grégoire JUGE wrote:

Hello,

I tried to replicate the current https://twistedmatrix.com/documents/current/index.html https://twistedmatrix.com/documents/current/index.html theme with pelican: https://judgegregg.github.io/pelitwi/ https://judgegregg.github.io/pelitwi/ (I reused Moshe Z.'s example to make comparison easier :) ) Sources: https://github.com/JudgeGregg/pelitwi 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 _______________________________________________ Twisted mailing list -- twisted@python.org To unsubscribe send an email to twisted-leave@python.org https://mail.python.org/mailman3/lists/twisted.python.org/ Message archived at https://mail.python.org/archives/list/twisted@python.org/message/RAUXUBSEGA3... Code of Conduct: https://twisted.org/conduct

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 a écrit :

On Wed, 18 Aug 2021 at 10:46, Grégoire JUGE 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 https://mail.python.org/mailman3/lists/twisted.python.org/ Message archived at https://mail.python.org/archives/list/twisted@python.org/message/52A7FAYRPAD... Code of Conduct: https://twisted.org/conduct