Here is an example of pages made using Sphinx: https://pgm.readthedocs.io/en/develop/
C > On Sep 7, 2016, at 11:29 PM, Johan Ström <jo...@stromnet.se> wrote: > >> On 08/09/16 00:13, Colin Reese wrote: >> What are the cons for a github-hosted wiki again? > Well, my only objection would be that it is a third party, but since > "we" don't really have a proper organization or funding or anything like > that which would naturally be able to "run it ourselfs", every solution > would become a third party in any way... > So, no, I don't have any cons for Github. >> >> It really seems to make sense to have all of the source and the how-to >> hosted in one place, in an easy to use and modify format. Admin and >> source control is easy to use (it is designed for it, after all), >> managed, and attached to the repo for owfs itself. This really seems >> like the obvious solution to me. >> >> https://help.github.com/articles/about-github-wikis/ > It should be noted that Github wikis and Github pages are two different > things: > > The Github wiki is inline in the repo UI, and features a basic WYSIWYG > editor (seems to support multiple markup methods). Either contributors > can edit, or all can edit, directly on site. > It doesn't seem easy to do vetting of edits though, i.e. "pull requests" > from contributors. Either you allow *everyone* to edit the wiki, or only > project collaborators (who can also commit code I guess?). It *is* > possible to manually handle the wiki as a git repo, and do merges that > way, but not via Github UI. > > The Github pages are just static files commited to a GIT repo, which are > then presented standalone (no github UI) on xxx.github.io (custom domain > supported too). > For pages, you *can* use the built-in preprocessing framework Jekyll. I > tried it out a bit yesterday, you just commit static files the same way, > but you can create separate layout files and do some automatic > processing such as iterate files in a directory, or data structures etc, > and produce appropriate output. So, html/markdown/"jekyll code"/others > as input, html as output (which is shown on xxx.github.io). > Quite powerful, but requires some manual work. There is no web editor, > so you must clone the repo and edit it locally, making the threshold to > contribute a bit higher. > > So both have pros and cons.. Regardless of which one we find most > suiting, I'd say we should keep all info in *one* place, and just use > the other for pointing to the first place. Don't have half of the info > in pages and wiki.. Or...? Perhaps basic info & best practices on Page, > and have non-collaborator contributions on wiki, where articles evolve > into best practices, which goes to the site? >> >> Colin >> >> >>> On 9/7/2016 3:03 PM, Jan Kandziora wrote: >>>> Am 07.09.2016 um 21:23 schrieb Johan Ström: >>>> Pro: >>>> - would be able to properly version it in git >>>> - Could integrate with automatic build on push, using pull requests for >>>> contribution etc. >>>> - static is simple >>>> Cons: >>>> - Depending on how it's implemented, it could be trickier to contribute. >>>> But most contributors are probably somewhat tech-savvy anyway.. >>> If we use "simple" markup, we have to pick a person who extends the >>> "simple" markup as needed. I don't like the idea of not being able to >>> draw a table in a certain way or arrange text around an image just >>> because the "simple" markup does not support what I need. > It's nice to be flexible, but to what extent? Are there any formatting > languages supporting this, that is not manual HTML? I would not want to > do manual HTML for the overall content, just because we need special > tables in once place. > If we go with GH Wiki, their markdown seems to support inline HTML. If > we go with GH Pages, we can do whatever we want. >>> >>> In reality, we don't need this "simple" markup when all the people who >>> are contributing to the documentation are developers. > If I understand you correct, you want something more powerful, perhaps > HTML or other? If so, I don't agree. Its not about making it simple for > computer-illiterate people to contribute, it's making it easy for *us* > to write docs and not have to worry about writing verbose HTML around > everything to make it readable. >>> >>> It's either user+developers, then cms/wiki is the way to go, or plain >>> old html files, with some preprocessing to put each article into a >>> common frame, suppling breadcrumbs and a table of contents >>> automatically. All inbetween will gives us a headache. > In the later option, if we'd use the Github Pages Jekyll approach, its > easy to use HTML where needed and Markup (or some other supported > language) where needed. > >>> >>> >>>> I'm going to lift a followup question: should we stay on sourceforge? >>>> Even if Github may be hyped and nowadays used by every granny and her >>>> cat, it *is* a lot better than Sourceforge when it comes to git.. and >>>> everything around it.. >>>> We would certainly not be the first project to leave SF.. They may not >>>> yet have covertly bundled installers and what not with owfs, but who >>>> knows.. >>>> (http://www.infoworld.com/article/2931753/open-source-software/sourceforge-the-end-cant-come-too-soon.html). >>> I have some old projects at sourceforge but yes, I've started new >>> projects on github only since some years ago. I would never again begin >>> a new project on sf.net. >>> >>> Why? Because sf.net is the yahoo of software. Totally bloated and full >>> of bells and whistles you don't want, with the main functions >>> complicated and brittle. > Good comparison... :) >>> >>> >>> >>>> I haven't looked at github pages much more than during writing message, >>>> but something like this is tempting: >>>> * Move project to github: git hosting, issue handling, pull requests. >>>> * Setup new github pages, automatically built by pushing to either main >>>> repo or a separate site repo. If we juse sphinx, jekyll, or plain >>>> markdown, or something else, I don't know. >>>> * Handle contributions to docs and source the same way: pull requests >>>> >>>> Github could thus handle: GIT, basic descriptions, issues, pull >>>> requests, pages (site), releases. >>>> However, not mailinglist. We could keep that at sourceforge though. >>> I would like to consolidate the ways to report problems and bugs. It's a >>> bit tedious to have this at so many locations. Sourceforge does a >>> terrible job translating between the different interfaces. >>> Any good plan how to migrate this? What should the mailing list be good >>> for in the future? Developers only? If yes, who is taking care for >>> people reporting problems and bugs on the github tracker? > Good questions! Issues and pull requests should always be the problem & > bug-reporting location imo. This lists however has a lot of non-bug > questions too, more like support request around hardware. Should that > become GH issues? Not too sure.. One upside with mailing list is that it > reaches your inbox, if you are subscribed. With github you have to watch > the project to be notified of new issues etc.. > I don't have an answer.. :) >>> >>> >>>> (as it happens, I just created https://github.com/owfs. If we're not >>>> going to use it, then at least so no-one else can steal it.. :)) >>> Fine. Please add me (ianka) to the organisation. > Done >>> >>> >>>>> If we had to rewrite from scratch, that would be an awful lot of work. >>>> That it would indeed.. But at the same time, we would need to go through >>>> everything and clean out a lot of old/bad examples anyway. I'd say, >>>> unless we're to keep the old site totally, we need to go through all >>>> pages and move/filter the content. >>> This, yes. My concern was about authorship and copyright mostly. >>> "© Copyright 2003-2016 - OWFS website" isn't a good thing to start with. > Hm. Well that is ambiguous.. I've mailed with Colin off-list concerning > the contents origins. I'll see if I can find out the origins of the (C) too. > > ------------------------------------------------------------------------------ > _______________________________________________ > Owfs-developers mailing list > Owfs-developers@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/owfs-developers ------------------------------------------------------------------------------ _______________________________________________ Owfs-developers mailing list Owfs-developers@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/owfs-developers
