[Scummvm-devel] Reigniting our docs effort

[Matan Bareket]

Thanks Lothar,
I'm hoping making to docs more accessible to editors will encourage
everyone on the team to contribute!

Eugene, with your blessing I'd like to start and create the docs repo and
copy (but not move) some of our existing docs into it as is, then start
editorializing it into a proper manual.

On Thu, Aug 9, 2018 at 10:40 AM Lothar Serra Mari <lserramari at gmail.com>
wrote:

> 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 <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
> >>>>>
> >>>>>
> >>>>
> >>
> >
> >
> >
> > _______________________________________________
> > Scummvm-devel mailing list
> > Scummvm-devel at lists.scummvm.org
> > http://lists.scummvm.org/listinfo/scummvm-devel
> >
> _______________________________________________
> 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/20180810/6540dde2/attachment-0001.html>