Improve documentation

[agriffard]

I am currently evaluating ReadTheDocs (https://readthedocs.org/) as an alternative to generate the documentation (a question have been raised during Orchard Harvest about the usage of this kind of documentation).

The choice to use .markdown files to edit the documentation has been made a long time ago because this is the easier way to allow people to contribute to it using a simple syntax.

Many open source projects, like the ASP.NET team (https://docs.asp.net), are currently using ReadTheDocs and accept pull requests.

It seems that one requirement is to host the generated files on readthedocs.org. You just associate a github repository to a RTD project and then it generates a new version of the docs each time you commit some changes.

The migration could be simple because you can easily specify a Markdown parser to generate the files from .markdown files.

Here are some benefits that can bring RTD:

• Free for Open source projects : http://read-the-docs.readthedocs.org/en/latest/open-source-philosophy.html
• Create and organize table of contents.
• Autogenerated index, integrated search.
• Modify your theme and add static css or scripts.
• Generate multiple docs, using different branches.
• Generate Html version but also Pdf or Epub from the sources.
• Support .rst files which has an interesting syntax and features.
• Possible sub-project or localized versions of the files.

[agriffard]

There has been a nice discussion between @abhishekluv and @rtpHarry about issues that have to be fixed and about ideas of improvements : Lists of OrchardDoc Issues to be fixed #188

[rtpHarry]

It does seem like a good solution but I haven't looked into it deeply.

Questions I would like to get documented as part of the debate are:

• What are the advantages of using ReadTheDocs over plain Sphinx?
• What are the disadvantages?
• Is the C# language support completed yet? (I know that somebody on the asp.net vnext team is working on this)

[bleroy]

What are the advantages of using ReadTheDocs over plain Sphinx? One is hosting the other. Not the same category.

[rtpHarry]

@bleroy maybe I didn't word it right, I understand it's a hosting service for Sphinx projects. I was just wondering why we would use readthedocs to build the sphinx output over doing it ourselves. I'm not for or against it at the moment just trying to think it though.

For example, if we replace the docs.orchardproject.net site with a readthedocs hosted subdomain then all our urls will change but we won't be in control of the domain to setup 301 redirects.

I've just looked into this particular example and it seems they have considered it and provided a user defined redirects mechanism but this is the sort of thing we need to discuss as part of the appraisal.

[bleroy]

Ah, ok, got it. Yes, the point is to reduce the number of tools that we have to build and manage, I think. This is why we moved translations from our custom tool to a third-party specialized crowd-sourced platform. Can you elaborate on redirects? I'm not sure I understand why we couldn't manage our own redirects from the current URLs.

[rtpHarry]

Because readthedocs supports custom domains so we can let them host it via a cname of docs.orchardproject.net (which is the current docs url and the logical place for it). Like I say though, readthedocs also supports user defined redirects so we can forward any of the old urls on to the equivalent url on the readthedocs powered site.

[bleroy]

Thanks, makes sense.

[agriffard]

I created a rtd branch and an OrchardDoc project on ReadTheDocs. You can see the result here : http://orcharddoc.readthedocs.org/en/rtd/index.html

I had to create some .rst files which are the TOC files and add title to each .markdown file to be used in the links (I made a tool to generate and update them).

[rtpHarry]

fyi I just tried this out and its borking with the latest builds.

When I run make html it fails with this:

# Sphinx version: 1.4.1
# Python version: 3.5.1 (CPython)
# Docutils version: 0.12 release
# Jinja2 version: 2.8
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "c:\users\rtpharry\appdata\local\programs\python\python35-32\lib\site-packages\sphinx\cmdline.py", line 243, in main
    opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
  File "c:\users\rtpharry\appdata\local\programs\python\python35-32\lib\site-packages\sphinx\application.py", line 132, in __init__
    confoverrides or {}, self.tags)
  File "c:\users\rtpharry\appdata\local\programs\python\python35-32\lib\site-packages\sphinx\config.py", line 289, in __init__
    execfile_(filename, config)
  File "c:\users\rtpharry\appdata\local\programs\python\python35-32\lib\site-packages\sphinx\util\pycompat.py", line 130, in execfile_
    exec_(code, _globals)
  File "conf.py", line 36, in <module>
    from recommonmark.parser import CommonMarkParser
ImportError: No module named 'recommonmark'

You can fix it by running pip install -U recommonmark though and then carrying on with make html

[agriffard]

I added the command 'pip install -U recommonmark' in the contributing.md