Re: Reigniting our docs effort

Lothar Serra Mari <[email protected]> Thu, 9 Aug 2018 16:40:41 +0200
Newsgroups	gmane.games.devel.scummvm
Message-ID	<[email protected]>
This all sounds very good to me. Let me know if you need any assistence.

Lothar

Am 09.08.2018 um 16:26 schrieb 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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
>>>>> [email protected]
>>>>> http://lists.scummvm.org/listinfo/scummvm-devel
>>>>>
>>>>>
>>>>
>>
> 
> 
> 
> _______________________________________________
> Scummvm-devel mailing list
> [email protected]
> http://lists.scummvm.org/listinfo/scummvm-devel
>

_______________________________________________
Scummvm-devel mailing list
[email protected]
http://lists.scummvm.org/listinfo/scummvm-devel
pEpkey.asc (application/pgp-keys, 2.4 KB)