Label/date the current documentation

[twisted-trac]

	@cyli reported
Trac ID	trac#3945
Type	task
Created	2009-08-01 03:20:43Z

As per the discussion on the mailing list, all the howto/tutorial documentation (not API docs, because they are automatically generated) should be labeled with:

• when it was last updated
• the version that was current when the doc was written/updated

What would be even more useful, although it would also be a lot more
work, is to perhaps link to a diff between the code as it is now and
as it was when the tutorial was written. Or just a changelog.

Searchable metadata

trac-id__3945 3945
type__task task
reporter__cyli cyli
priority__normal normal
milestone__ 
branch__ 
branch_author__ 
status__closed closed
resolution__fixed fixed
component__core core
keywords__documentation_review documentation review
time__1249096843000000 1249096843000000
changetime__1612879003667740 1612879003667740
version__None None
owner__None None
cc__thijs cc__jesstess cc__khorn

[twisted-trac]

	@glyph removed owner

[twisted-trac]

	@khorn set owner to @khorn

after the Sphinx conversion, this should be done using Sphinx's "file-wide metadata" field list:

http://sphinx.pocoo.org/markup/misc.html#file-wide-metadata

perhaps in conjunction with SVN keyword substitution for the date (Sphinx should clean up the icky dollar signs automatically...but I haven't tested it yet.

Then the Sphinx template will need to be modified to display this information in generated docs...it won't be shown automatically.

[twisted-trac]

	@thijstriemstra commented

#5380 adds a "Go to the latest version of this document." link at the top of the page.

[twisted-trac]

	@thijstriemstra commented

The Sphinx docs contains some extra data in the footer:

© Copyright 2014, Twisted Matrix Labs. Revision 970ef0607c3fb3f1568db834a19985aefbe5f007. 

But this can also include a date and version number as suggested.

[twisted-trac]

	@adiroiban set owner to @adiroiban

There was not much activity here

We have https://docs.twistedmatrix.com/en/twisted-19.7.0/conch/index.html

There you can see the version in the URL

---

The problem is that we also have https://docs.twistedmatrix.com/en/stable/

and here you have no idea what version is in use.

---

As commented above, we can include the version in the Sphinx footer

© Copyright 2021, Twisted Matrix Labs. Version 1.2.3,  Revision 970ef0607

This will conflict with https://docs.twistedmatrix.com/en/latest/ which will have a fixed version but ever changing revision.

Maybe this can be fixed by always having DEV_VERSION in the main branch, and the a actual version is only set in the release branch.

[twisted-trac]

	@adiroiban removed owner

PR at #1509

[twisted-trac]

	@adiroiban set status to closed