I spoke the CMF guys (mainly@dbu ) this weekend and they are going to follow our documentation standards. Now it's used in more project, I've moved it outside the overview document and inside it's own document.

There are also some other things which needs some discussion (things that are added in this PR are things that I and the CMF guys like to see in the standards, but if people are -1 for it, it gets removed):

Added standards on which characters to use for heading levels -Sphinx doesn't have specific level specific character, they should be documented somewhere
Added a standard about inline hyperlinks vs the once we use
Added standards about the needed formats -Without this, all@ricardclau's and my work needs to get done again 😉

Copy link

Contributor

pvolok commentedApr 8, 2013

After writing some docs it feels painful to add links. For instance, if I want to write something like"you can read more here".

Is there a way writing like:

read `here<alias>`_..... _`alias`: http://...

weaverryan reviewed

Apr 17, 2013

View reviewed changes

contributing/documentation/standards.rst

		shorthand);
		* Inline hyperlinks are not used. Seperate the link and their target
		definition, which you add on the bottom of the page;
		* You should use a form of you instead of we.

Copy link

Member

weaverryanApr 17, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

How about an example below all of this that shows these rules in action (as much as possible).

Copy link

MemberAuthor

wouterjApr 20, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I like that. I need to think of a good example, it's hard to put most standards in one example without the example being to dummy... :)

Copy link

Member

weaverryan commentedApr 17, 2013

Very nice changes Wouter! Don't forget the map and index changes for the new doc.

I have no problems with the 3 items you listed above - we're already been doing these things, I think it's great to formalize it.

Copy link

MemberAuthor

wouterj commentedApr 23, 2013

@pvolok I had a look into the ReSt and Sphinx specs, but it's not possible. The only thing that's possible is using anonymous targets, but that makes the doc even unreadable :)