[Scummvm-devel] Reigniting our docs effort

[Matan Bareket]

1. Sphinx can export as both PDF, EPUB and HTML. We can impose a style
guide that will impose a 79 characters line length in the source files
(when rendered, line breaks are ignored between rows and paragraphs are
separated by an empty line)
2. Yes, I see our FAQ being much much smaller with a proper doc site.
here's an example of a FAQ structure and links:
http://docs.readthedocs.io/en/latest/faq.html#my-project-isn-t-building-with-autodoc


On Thu, Aug 9, 2018 at 9:52 AM Eugene Sandulenko <sev at scummvm.org> wrote:

> Okay.
>
> I have a couple of questions then:
>
>   1. Will it be possible to export the result into an 80-columns text
> format, so we could ship it as part of the distribution?
>   2. Would it be possible to have fixed reference URLs for the relevant
> FAQ items?
>
>
> Eugene
>
> On 9 August 2018 at 12:26, Matan Bareket <mataniko at gmail.com> wrote:
>
>> I'm proposing to start with converting both the User Manual and the
>> README to the new format as sort of a v.1 and then start editing everything
>> together into something more cohesive.
>>
>> Some of the FAQ is redundant today, for example the introduction section,
>> supported games section, parts of running games - all of these are covered
>> either in the manual or the README. Other parts are not.
>>
>> Eventually the new docs hub should cover most of the FAQ and migrate the
>> rest.
>>
>> On Thu, Aug 9, 2018 at 2:11 AM Eugene Sandulenko <sev at scummvm.org> wrote:
>>
>>> The idea to renew the documentation is always nice.
>>>
>>> Which one are you referring to? Our README? Our User Manual?
>>>
>>> Why do you think, FAQ is redundant? I do not remember its content being
>>> covered anywhere else.
>>>
>>>
>>> Eugene
>>>
>>> On 7 August 2018 at 22:28, Matan Bareket <mataniko at gmail.com> wrote:
>>>
>>>> Team,
>>>>
>>>> I want to try and reignite our documentation effort which will
>>>> eventually consolidate all of the disparate docs we have (doxygen, site
>>>> pages, quickstart, wiki, readme) into one central location.
>>>>
>>>> In order to do so, i'd like to do the following:
>>>>
>>>>    1. Create a new repo called scummvm-docs
>>>>    2. Convert existing docs into reStructredText - Initial pass won't
>>>>    make much sense but it will be a good place to work off.
>>>>    3. Eliminate redundant information - For example the FAQ on the
>>>>    website. The wiki will be focused on more developer related items.
>>>>    4. Use readthedocs to host & manage docs
>>>>
>>>> A few notes: https://readthedocs.org/ is a free service that takes
>>>> care of the headaches of managing by automatically synchronizing with the
>>>> docs repo. It also uses Sphinx to create the documentation, it also
>>>> supports multiple languages so we can hook it up to weblate for translators
>>>> to work off.
>>>>
>>>> There are a few doxygen to sphinx parsers, but it's more of a phase 2.
>>>>
>>>> Hopefully getting everything we have now into one central location that
>>>> can be easily updated via git will encourage active work on our docs.
>>>>
>>>> One caveat to readthedocs is that they place a single ethical ad on the
>>>> sidebar. We can potentially host everything ourselves if it's a big issue.
>>>>
>>>> Some sample sites on readthedocs:
>>>> https://docs.phpmyadmin.net/en/latest/
>>>> http://docs.godotengine.org/en/3.0/
>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> Scummvm-devel mailing list
>>>> Scummvm-devel at lists.scummvm.org
>>>> http://lists.scummvm.org/listinfo/scummvm-devel
>>>>
>>>>
>>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.scummvm.org/pipermail/scummvm-devel/attachments/20180809/6e8ad00e/attachment-0001.html>