[Twisted-Python] Development documentation in Trac wiki
Hi,
I would like to talk about moving Twisted development documentation out of official Twisted doc.
They can be moved either into the Trac wiki or a separate project ... maybe twisted-dev-tools
The problem with Twisted main repo is that (AFAIK) updates are done only after a release... so I change might be delay quite a lot (6 months)
We already have a lot of info inside the Trac wiki..
My plan it to move the following docs into Trac and organize existing specification and development wiki pages:
http://twistedmatrix.com/documents/current/core/specifications/index.html http://twistedmatrix.com/documents/current/core/specifications/banana.html http://twistedmatrix.com/documents/current/core/development/index.html http://twistedmatrix.com/documents/current/core/development/naming.html http://twistedmatrix.com/documents/current/core/development/philosophy.html http://twistedmatrix.com/documents/current/core/development/security.html
I would also move the following docs to Trac so that they can be updated much faster.
http://twistedmatrix.com/documents/current/core/development/policy/svn-dev.h... http://twistedmatrix.com/documents/current/core/development/policy/index.htm... http://twistedmatrix.com/documents/current/core/development/policy/coding-st... http://twistedmatrix.com/documents/current/core/development/policy/writing-s... http://twistedmatrix.com/documents/current/core/development/policy/test-stan...
http://twistedmatrix.com/documents/current/core/development/policy/doc-stand... Do we still use XHTML ?
Trac support RST format, so we can maintain those pages in RST... and trac wiki allow to view changes as diffs.
Having docs in repo is nice as you can send them for review, but i feel that this is counter-productive for the current case.
What do you think?
Thanks!
On 02:35 pm, adi@roiban.ro wrote:
Hi,
I would like to talk about moving Twisted development documentation out of official Twisted doc.
They can be moved either into the Trac wiki or a separate project ... maybe twisted-dev-tools
The problem with Twisted main repo is that (AFAIK) updates are done only after a release... so I change might be delay quite a lot (6 months)
The coding standard really shouldn't be changing so frequently that this is a major concern. Additionally, everyone who is developing Twisted has a Twisted checkout with the most recent version of the information anyway.
Also, releases *should* be happening more frequently than every six months.
This doesn't seem like a very compelling reason to make this change.
Jean-Paul
We already have a lot of info inside the Trac wiki..
My plan it to move the following docs into Trac and organize existing specification and development wiki pages:
http://twistedmatrix.com/documents/current/core/specifications/index.html http://twistedmatrix.com/documents/current/core/specifications/banana.html http://twistedmatrix.com/documents/current/core/development/index.html http://twistedmatrix.com/documents/current/core/development/naming.html http://twistedmatrix.com/documents/current/core/development/philosophy.html http://twistedmatrix.com/documents/current/core/development/security.html
I would also move the following docs to Trac so that they can be updated much faster.
http://twistedmatrix.com/documents/current/core/development/policy/svn- dev.html http://twistedmatrix.com/documents/current/core/development/policy/index.htm... http://twistedmatrix.com/documents/current/core/development/policy /coding-standard.html http://twistedmatrix.com/documents/current/core/development/policy /writing-standard.html http://twistedmatrix.com/documents/current/core/development/policy /test-standard.html
http://twistedmatrix.com/documents/current/core/development/policy/doc- standard.html Do we still use XHTML ?
Trac support RST format, so we can maintain those pages in RST... and trac wiki allow to view changes as diffs.
Having docs in repo is nice as you can send them for review, but i feel that this is counter-productive for the current case.
What do you think?
Thanks!
-- Adi Roiban
Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
On Sat, Feb 7, 2015 at 9:29 AM, exarkun@twistedmatrix.com wrote:
On 02:35 pm, adi@roiban.ro wrote:
Hi,
I would like to talk about moving Twisted development documentation out of official Twisted doc.
They can be moved either into the Trac wiki or a separate project ... maybe twisted-dev-tools
The problem with Twisted main repo is that (AFAIK) updates are done only after a release... so I change might be delay quite a lot (6 months)
The coding standard really shouldn't be changing so frequently that this is a major concern. Additionally, everyone who is developing Twisted has a Twisted checkout with the most recent version of the information anyway.
Also, releases *should* be happening more frequently than every six months.
This doesn't seem like a very compelling reason to make this change.
Jean-Paul
I think a better plan would be to complete https://twistedmatrix.com/trac/ticket/1140
Kevin Horn
We already have a lot of info inside the Trac wiki..
My plan it to move the following docs into Trac and organize existing specification and development wiki pages:
http://twistedmatrix.com/documents/current/core/specifications/index.html http://twistedmatrix.com/documents/current/core/ specifications/banana.html http://twistedmatrix.com/documents/current/core/development/index.html http://twistedmatrix.com/documents/current/core/development/naming.html http://twistedmatrix.com/documents/current/core/ development/philosophy.html http://twistedmatrix.com/documents/current/core/development/security.html
I would also move the following docs to Trac so that they can be updated much faster.
http://twistedmatrix.com/documents/current/core/development/policy/svn- dev.html http://twistedmatrix.com/documents/current/core/ development/policy/index.html http://twistedmatrix.com/documents/current/core/development/policy /coding-standard.html http://twistedmatrix.com/documents/current/core/development/policy /writing-standard.html http://twistedmatrix.com/documents/current/core/development/policy /test-standard.html
http://twistedmatrix.com/documents/current/core/development/policy/doc- standard.html Do we still use XHTML ?
Trac support RST format, so we can maintain those pages in RST... and trac wiki allow to view changes as diffs.
Having docs in repo is nice as you can send them for review, but i feel that this is counter-productive for the current case.
What do you think?
Thanks!
-- Adi Roiban
Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
On Feb 7, 2015, at 11:24 AM, Kevin Horn kevin.horn@gmail.com wrote:
I think a better plan would be to complete https://twistedmatrix.com/trac/ticket/1140 https://twistedmatrix.com/trac/ticket/1140
This is already done, after a fashion. https://twisted.readthedocs.org/en/latest/ https://twisted.readthedocs.org/en/latest/ is generated after each commit, as part of the sync to github, as you can see here: https://readthedocs.org/builds/twisted/?fromdocs=twisted
Our buildbot also builds the docs (with the website stylesheet) after each commit, it just doesn't give them a stable URL.
-glyph
On Feb 7, 2015, at 6:35 AM, Adi Roiban adi@roiban.ro wrote:
Trac support RST format, so we can maintain those pages in RST... and trac wiki allow to view changes as diffs.
How does one enable RST formatting in trac? I don't love RST but it would certainly be a better source format than trac-wiki syntax.
On 7 February 2015 at 20:32, Glyph glyph@twistedmatrix.com wrote:
On Feb 7, 2015, at 6:35 AM, Adi Roiban adi@roiban.ro wrote:
Trac support RST format, so we can maintain those pages in RST... and trac wiki allow to view changes as diffs.
How does one enable RST formatting in trac? I don't love RST but it would certainly be a better source format than trac-wiki syntax.
https://twistedmatrix.com/trac/wiki/WikiRestructuredText
On Feb 7, 2015, at 6:35 AM, Adi Roiban adi@roiban.ro wrote:
What do you think?
I'd prefer to go the opposite direction, and take all the policy documents on the wiki and put them into the repository. Originally, the intention of putting stuff on the wiki was to have a rough draft for something that was not official, but would become so when it went through code review and went into the repository.
Right now many changes to these de-facto official policies happen with only a cursory mailing list discussion, so they don't necessarily reflect the consensus process that we have designed for code.
It's worth noting that CompatibilityPolicy is still provisional because our code still emits warnings, and we should fix those :-).
-glyph
participants (4)
-
Adi Roiban -
exarkun＠twistedmatrix.com -
Glyph -
Kevin Horn