Re: [ft-devel] Questions related to current Documentation (and changes)

[Nikolaus Waxweiler]

It just occurred to me that Rust (or rustdoc) can handle documentation in
source code in Markdown format and generate static docs from that. Maybe
something for a bit of inspiration.
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] Questions related to current Documentation (and changes)

[Werner LEMBERG]

> I'd like to know whether the project also involves converting the
> non-documentation pages (Home page, Overview etc.) to markdown, so
> that the whole site can be deployed at once?

As Nikolaus has answered: yes.  However, the main focus should be on
the technical issues, not the contents.  In other words, a raw,
automated translation from HTML to markdown in the source code is
fully sufficient.

> I was also thinking about how the API documentation will be
> generated after the Markdown porting is complete.  Will the
> 'converter' that we select be supplied with the source code of the
> docmaker so that the markdown can be converted to HTML when `make
> refdoc` or equivalent is called?

Basically, this is not important.  I don't mind if I have to install
an additional tool for processing the API documentation in case this
is the most convenient way.  What I want is the following.

  1. Edit the API documentation (in markdown format) in a C header
 file.

  2. Call `make refdoc' to get nicely formatted HTML of the whole API
 that I can include stand-alone in the FreeType tarball.

  3. Call `make markdown' (or something similar) to create markdown
 files that I can copy to the freetype-web repository.  Within the
 freetype-web repository I then want to say `make web' to get
 nicely formatted HTML that is integrated into the FreeType
 website.

I'm not sure whether step 3 is necessary – right now, I simply copy
the HTML pages created by docmaker to the freetype-web repository...


Werner
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] Questions related to current Documentation (and changes)

[Nikolaus Waxweiler]

Yes, the homepage should be converted, too, unless Werner wants to continue
to maintain bare HTML files :D
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] Questions related to current Documentation (and changes)

[Nikhil Ramakrishnan]

Hi,

I'd like to know whether the project also involves converting the
non-documentation pages (Home page, Overview etc.) to markdown, so that the
whole site can be deployed at once?

I was also thinking about how the API documentation will be generated after
the Markdown porting is complete. Will the 'converter' that we select be
supplied with the source code of the docmaker so that the markdown can be
converted to HTML when `make refdoc` or equivalent is called?

I'll add those parts to the proposal, and send an initial draft soon.


Regards,

--
Nikhil
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] Questions related to current Documentation (and changes)

[Werner LEMBERG]

> While I'm looking through some of the code, what would you suggest I
> go through except the `docmaker` and `/docs` to get an idea about
> how the docmaker works?

Unfortunately, `docmaker' is completely undocumented.  However, the
source code is quite readable IMHO and shouldn't be too difficult to
understand.  I'm not a python expert, and in particular no expert for
object-oriented programming, but I was able to do bug fixes and add
tiny extensions here and there :-)

I'm happy to apply patches of any kind in case you find bug or want to
contribute improvements (fixes and changes to `docmaker' that are not
directly related to the GSoC project goal can be applied any time).


Werner

___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] Questions related to current Documentation (and changes)

[Nikhil Ramakrishnan]

Hi,

Thanks for that information. I'd like to get a rough idea of how things
work before I start working on the proposal

While I'm looking through some of the code, what would you suggest I go
through except the `docmaker` and `/docs` to get an idea about how the
docmaker works?


Regards,

-- 
Nikhil Ramakrishnan.
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] Questions related to current Documentation (and changes)

[Werner LEMBERG]

> I think I'll start working on a proposal for this!

Ok, great!

> Is there a specific format required by FreeType?

No.

> What are the things you would suggest to include in the proposal?

https://google.github.io/gsocguides/student/writing-a-proposal

Remember: We have to base our GSoC student selection primarily on the
submitted proposals!

> I will try to get a draft ready ASAP and send it across before I
> submit on the GSoC website (is that okay?).

Yes, please do so.


Werner

___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] Questions related to current Documentation (and changes)

[Nikhil Ramakrishnan]

Hey,

Sorry for the late reply, I was traveling.

I think I'll start working on a proposal for this! Is there a specific
format required by FreeType? What are the things you would suggest to
include in the proposal? I will try to get a draft ready ASAP and send it
across before I submit on the GSoC website (is that okay?).

Regards,

On 24 February 2018 at 20:41, Werner LEMBERG  wrote:

>
> > What you're trying to say is that this project also involves
> > *manual* conversion of the current tutorials etc. to markdown?
>
> Well, for testing purposes you have to check whether everything's
> working, no?  So at least *some* part of the documentation should be
> converted – maybe you can even use pandoc for that since I took great
> care to have meaningful HTML :-) It is not necessary to handle
> everything, since this is a dull job without technical merits.[*]
>
> > Also (please correct me if I'm wrong) , the current docs is
> > generated [...] with `make refdoc`, right?
>
> Correct.
>
> > This currently generates HTML files as output documentation from
> > [...] docmaker, and changing this so that the output is in Markdown
> > is also in the scope of this project?
>
> Yes.  I believe that `docmaker' or maybe something new can be
> simplified: Instead of extracting the documentation and converting it
> to HTML (and resolving cross references) it would be sufficient to
> extract the documentation (and resolving cross references).  The
> conversion from markdown to HTML should be done by an external tool.
>
> To summarize: The project consists of
>
> (1) updating `docmaker' to emit markdown but still resolving cross
> references;
>
> (2) updating `make refdoc' so that it handle (1) and emits
> ready-to-view HTML (which will become part of the distribution
> tarball);
>
> (3) converting the remaining HTML documentation of FreeType 2 (in the
> repository https://cgit.freedesktop.org/freetype/freetype-web) to
> markdown – at least partially for testing purposes; and
>
> (4) providing an HTML framework and CSS stylesheets (or whatever is
> necessary) so that the documentation in markdown format can be
> converted to static HTML with a call to `make' or something
> similar, taking away the burden to generate and/or adjust the site
> navigation of www.freetype.org.
>
> Note that the markdown stuff created by (1) will be simply copied and
> committed into the `freetype-web' repository, and it should also be
> part of www.freetype.org (as it currently already is).
>
>
> Werner
>
>
> [*] Guess who will be doing this dull job :-/
>



-- 
Nikhil Ramakrishnan.
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] Questions related to current Documentation (and changes)

[Werner LEMBERG]

> What you're trying to say is that this project also involves
> *manual* conversion of the current tutorials etc. to markdown?

Well, for testing purposes you have to check whether everything's
working, no?  So at least *some* part of the documentation should be
converted – maybe you can even use pandoc for that since I took great
care to have meaningful HTML :-) It is not necessary to handle
everything, since this is a dull job without technical merits.[*]

> Also (please correct me if I'm wrong) , the current docs is
> generated [...] with `make refdoc`, right?

Correct.

> This currently generates HTML files as output documentation from
> [...] docmaker, and changing this so that the output is in Markdown
> is also in the scope of this project?

Yes.  I believe that `docmaker' or maybe something new can be
simplified: Instead of extracting the documentation and converting it
to HTML (and resolving cross references) it would be sufficient to
extract the documentation (and resolving cross references).  The
conversion from markdown to HTML should be done by an external tool.

To summarize: The project consists of

(1) updating `docmaker' to emit markdown but still resolving cross
references;

(2) updating `make refdoc' so that it handle (1) and emits
ready-to-view HTML (which will become part of the distribution
tarball);

(3) converting the remaining HTML documentation of FreeType 2 (in the
repository https://cgit.freedesktop.org/freetype/freetype-web) to
markdown – at least partially for testing purposes; and

(4) providing an HTML framework and CSS stylesheets (or whatever is
necessary) so that the documentation in markdown format can be
converted to static HTML with a call to `make' or something
similar, taking away the burden to generate and/or adjust the site
navigation of www.freetype.org.

Note that the markdown stuff created by (1) will be simply copied and
committed into the `freetype-web' repository, and it should also be
part of www.freetype.org (as it currently already is).


Werner


[*] Guess who will be doing this dull job :-/
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] Questions related to current Documentation (and changes)

[Nikhil Ramakrishnan]

Hi,

Thanks for the reply.

What you're trying to say is that this project also involves *manual*
conversion of the current tutorials etc. to markdown?

Also (please correct me if I'm wrong) , the current docs is generated at
root /docs
/
reference
/
with `make refdoc`, right? This currently generates HTML files as output
documentation from the code at root
/src
/tools
/
docmaker
,
and changing this so that the output is in Markdown is also in the scope of
this project?

Regards,

On 24 February 2018 at 16:16, Werner LEMBERG  wrote:

>
> Hello Nikhil!
>
>
> > I had a look at the gsoc project ideas, and am interested in
> > "Convert FreeType's HTML documentation to markdown."
>
> Thanks for your interest.
>
> > What I understand:
> >
> >   *The current docmaker processes the source, extracts the required
> >   data for documentation, and converts it into a readable format in
> >   HTML.*
> >
> > What the project expects:
> >
> >   *Write code so that the documentation can also be generated in
> >   markdown, and be converted to HTML.*
> >
> > Am I right?
>
> Good question.  It probably doesn't make sense to *generate* markdown.
> I consider markdown rather as an input format, and the FreeType
> documentation itself (i.e., both the stuff in the C header files and
> the remaining data like the tutorial) should be converted to markdown
> – with extensive cross-referencing as already present in the FreeType
> HTML output.
>
> To evaluate whether `docmaker' should be retained and modified, or
> whether it could be replaced with `something better' (whatever this
> is) is part of the problem.  We are open to suggestions here.
>
> > I have a few questions:
> >
> > 1) After this change, will the documentation be generated solely in
> >markdown and *later* be converted to other formats?
>
> No, the documentation should rather be *written* in markdown, see
> above.  Do you have another idea?
>
> > 2) Does this require a stylized markdown, or the basics (such as
> >GFM)?
>
> [GFM is GitHub's markdown flavour.]  This depends on the used
> conversion tool.  Looking at this flavour, I don't see anything
> particularly important for FreeType – for example, all code blocks are
> in the C language, so there is no special need to support
>
>   ```foo
>   blabla
>   ```
>
> On the other hand, we are currently using `@foo' for
> cross-referencing, which is more convenient to type than
> `[foo](#foo)'...  Maybe this can be retained?
>
> > 3) If (1) is true, will Pandoc be used to convert the docs to html
> >for the website?
>
> As mentioned above, this is not cast in stone, but right now I don't
> see a reason to not use it.  I very much like `pandoc', and it is very
> actively developed, covering an amazing bunch of output formats.  I
> don't say that this is the markdown to html generator of choice, but
> it seems like a good start.
>
> > [...]  If you could also recommend any other projects that you think
> > is suitable for me, I can start working on a proposal, and take your
> > inputs and comments before submission.
>
> Is there anything else besides FreeType? :-)
>
>
> Werner
>



-- 
Nikhil Ramakrishnan.
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel

Re: [ft-devel] Questions related to current Documentation (and changes)

[Werner LEMBERG]

Hello Nikhil!


> I had a look at the gsoc project ideas, and am interested in
> "Convert FreeType's HTML documentation to markdown."

Thanks for your interest.

> What I understand:
>
>   *The current docmaker processes the source, extracts the required
>   data for documentation, and converts it into a readable format in
>   HTML.*
>
> What the project expects:
>
>   *Write code so that the documentation can also be generated in
>   markdown, and be converted to HTML.*
>
> Am I right?

Good question.  It probably doesn't make sense to *generate* markdown.
I consider markdown rather as an input format, and the FreeType
documentation itself (i.e., both the stuff in the C header files and
the remaining data like the tutorial) should be converted to markdown
– with extensive cross-referencing as already present in the FreeType
HTML output.

To evaluate whether `docmaker' should be retained and modified, or
whether it could be replaced with `something better' (whatever this
is) is part of the problem.  We are open to suggestions here.

> I have a few questions:
>
> 1) After this change, will the documentation be generated solely in
>markdown and *later* be converted to other formats?

No, the documentation should rather be *written* in markdown, see
above.  Do you have another idea?

> 2) Does this require a stylized markdown, or the basics (such as
>GFM)?

[GFM is GitHub's markdown flavour.]  This depends on the used
conversion tool.  Looking at this flavour, I don't see anything
particularly important for FreeType – for example, all code blocks are
in the C language, so there is no special need to support

  ```foo
  blabla
  ```

On the other hand, we are currently using `@foo' for
cross-referencing, which is more convenient to type than
`[foo](#foo)'...  Maybe this can be retained?

> 3) If (1) is true, will Pandoc be used to convert the docs to html
>for the website?

As mentioned above, this is not cast in stone, but right now I don't
see a reason to not use it.  I very much like `pandoc', and it is very
actively developed, covering an amazing bunch of output formats.  I
don't say that this is the markdown to html generator of choice, but
it seems like a good start.

> [...]  If you could also recommend any other projects that you think
> is suitable for me, I can start working on a proposal, and take your
> inputs and comments before submission.

Is there anything else besides FreeType? :-)


Werner
___
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel