search

hyperboria / docs

Documentation for cjdns and Hyperboria
https://docs.meshwith.me
196 stars 71 forks source link

Transition to Sphinx for rendering #42

Open thefinn93 opened 8 years ago

thefinn93 commented 8 years ago

Don't merge this yet, I just want a unified discussion thread. I added the stuff to do Sphinx rendering, and setup a demo at docs2.meshwith.me and h.docs2.meshwith.me. Lemme know what you think. I assume we'll want to theme it eventually, but at this point I suspect there's a lot of stuff that doesn't render properly that i'd like to track down.

kpcyrd commented 8 years ago

Looks nice and I like the default theme! It looks like all links are currently broken, we'd need to switch those from .html to .md, which would break links in github.

Kubuxu commented 8 years ago

IIRC @thefinn93 was saying something about just doing nginx rewriting. It might not be him but either way it would be good solution.

thefinn93 commented 8 years ago
  1. Sphinx is supposed to convert the links. I don't know why it isn't. That was the main thing i wanted to fix before moving to this
  2. Nginx rewriting is just for serving analytics javascript. If they're coming from hype, they get the hype version of the analytics server, and vice versa.
  3. I think there are better themes out there, but for now the default one is acceptable
benhylau commented 8 years ago

Like these messed up section headers: https://docs2.meshwith.me/config/shorewall-and-vpn-gateway-howto.html

Trimardio commented 8 years ago

Like these messed up section headers: https://docs2.meshwith.me/config/shorewall-and-vpn-gateway-howto.html

This particular file isn't valid as .md because there is a lack of spaces between "#" and the words. Well actually github and browser apparently support this very well but sphinx doesn't by default, and I don't really see a way to change it, because that would involve changing the text of the files before sphinx process it and I have still have no idea how to do that.

Most of the change I was able to do where after the process by sphinx.

Should we simply fix the files that forgot the spaces between "#" and the title?

ansuz commented 7 years ago

Yes, we should fix the files. Most Markdown processors require them.

Trimardio commented 7 years ago

So I made some modifications. I'm not really satisfied with the result, but I'm not too sure what to change, so feedback is very welcome!

http://ns346455.ip-91-121-136.eu/hyperboria-docs/_build/html/

Modifications: -capacity to switch between pages -highlight of current page in the menu -added "todo" pages -menu is separated between current page chapter on top and all pages in the website (that's the weirdest thing I introduced in here, does anyone have an idea to avoid this from a design point of view?)

Also I know Danielo was working on some new design ideas he had and it looked very promising, does anyone know if he is still around?

ansuz commented 7 years ago

Looks pretty good. Thanks.

I'll review more thoroughly in a few days and see about pulling things in.

jonathancross commented 5 years ago

Is this still being worked on?

ansuz commented 5 years ago

not by me

Trimardio commented 5 years ago

Not currently but I have some spare time coming soon, so if you have any suggestion I'm all ears