Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Mailing lists / fpc-pascal / 2021-01

FPDoc now with Markdown support

7 messages · 4 people · –

Reply by email Subscribe to this list Your subscription

Read-only archive. Use j and k to move between messages.

Michael Van Canneyt

Hello !

I didn't make it quite in time for the new year, but still:

The fpdoc engine (what is used to document the FPC & Lazarus units) is now capable of outputting the documentation in markdown.

This can be used as input for mkdocs or another engine such as sphinx. As a first engine, I tackled mkdocs.

Compare the official page for TObject.Dispatch:

https://www.freepascal.org/docs-html/current/rtl/system/tobject.dispatch.html

With the following pages:

They are all the same documentation page, but just use a different theme for mkdocs:

gitbook theme:
https://www.freepascal.org/~michael/docs-demo/gitbook/system/tobject.dispatch/

ivory theme:
https://www.freepascal.org/~michael/docs-demo/ivory/system/tobject.dispatch/

windmill theme: (seems broken)
https://www.freepascal.org/~michael/docs-demo/windmill/system/tobject.dispatch/

windmill dark theme: (seems broken)
https://www.freepascal.org/~michael/docs-demo/windmill-dark/system/tobject.dispatch/

docskimmer theme:
https://www.freepascal.org/~michael/docs-demo/docskimmer/system/tobject.dispatch/

default (mkdocs) theme:
https://www.freepascal.org/~michael/docs-demo/windmill-dark/system/tobject.dispatch/

readthedocs theme:
https://www.freepascal.org/~michael/docs-demo/readthedocs/system/tobject.dispatch/

material theme:
https://www.freepascal.org/~michael/docs-demo/material/system/tobject.dispatch/

Some themes work better than others.

Fun fact:
Generating the documentation in HTML with fpdoc takes a couple of seconds. Depending on the theme, generating the docs with mkdocs (written in Python) takes 3-7 minutes.

Just shows that Pascal code is very efficient, I suppose... ;-)

I've been looking at allowing markdown for the description files (they would be less verbose then), but there seems to be no decent markdown parser available for pascal. If somone cares to contribute one...

Enjoy,

Michael.

Reply by email

Noel Duffy
to Michael Van Canneyt
Michael Van Canneyt wrote 9 lines
Hello ! I didn't make it quite in time for the new year, but still: The fpdoc engine (what is used to document the FPC & Lazarus units) is now capable of outputting the documentation in markdown. This can be used as input for mkdocs or another engine such as sphinx. As a first engine, I tackled mkdocs.

Great work! Thought I recognised some of these themes, then saw readthedocs in the list of themes.

Now we can start a long bitter bikeshedding thread about which theme to use for the official docs ;-)

[snipped]

I've been looking at allowing markdown for the description files (they would be less verbose then), but there seems to be no decent markdown parser available for pascal. If somone cares to contribute one...

I remember needing something like Markdown about a year or two ago, but gave up after reading the spec and seeing how vague and hand-wavey it was. I ended up going with a custom format instead. Not much help to you, I'm afraid.

Reply by email

Marco van de Voort
to Michael Van Canneyt: Hello ! I didn't make it quite in time for the new year, but still: The fpdoc engine…

Op 2021-01-02 om 15:31 schreef Michael Van Canneyt via fpc-pascal:

Show quoted text 7 lines
Hello ! I didn't make it quite in time for the new year, but still: The fpdoc engine (what is used to document the FPC & Lazarus units) is now capable of outputting the documentation in markdown.

After this update I get exceptions on

dwriter.pp:405
405       FreeAndNil(FPageInfos);

In the free event, shutting down fpdoc (chm is already written)

The traceback is convoluted(debian x86-64), but looks like:

#0  DESTROY (this=0x7ffff5b0a340, vmt=0x0) at fpdoc/dwriter.pp:405 #1  0x00000000000000a0 in ?? ()
#2  0x0000000000000001 in ?? ()
#3  0x00007ffff5b0a340 in ?? ()
#4  0x00000000004a7656 in DESTROY (this=0x7ffff5b0a340, vmt=0x0)     at fpdoc/dw_html.pp:261
#5  0x0000000000621738 in VMT_$DW_CHM_$$_TFPDOCCHMWRITER$indirect () #6  0x00007ffff7d4d818 in ?? ()
#7  0x0000000000000005 in ?? ()
#8  0x00000000004157e7 in FREE (this=0xa0) at ../inc/objpas.inc:336 #9  0x00007fffffffdbc0 in ?? ()
#10 0x00000000004cf5c8 in CREATEOUTPUT (this=0x7ffff7fbb100,     APACKAGE=0x7ffff77c28a0, ENGINE=0x7ffff7fbb280) at fpdoc/mkfpdoc.pp:249

Reply by email

Michael Van Canneyt
to Marco van de Voort
Marco van de Voort wrote 16 lines
Op 2021-01-02 om 15:31 schreef Michael Van Canneyt via fpc-pascal: > > Hello ! > > I didn't make it quite in time for the new year, but still: > > The fpdoc engine (what is used to document the FPC & Lazarus units) is > now capable of outputting the documentation in markdown. After this update I get exceptions on dwriter.pp:405 405       FreeAndNil(FPageInfos); In the free event, shutting down fpdoc (chm is already written)

Should be fixed in rev. 47981

Michael.

Reply by email

Bo Berglund
to Michael Van Canneyt: Hello ! I didn't make it quite in time for the new year, but still: The fpdoc engine…

On Sat, 2 Jan 2021 15:31:11 +0100 (CET), Michael Van Canneyt via fpc-pascal

Show quoted text 8 lines
Hello ! I didn't make it quite in time for the new year, but still: The fpdoc engine (what is used to document the FPC & Lazarus units) is now capable of outputting the documentation in markdown.

Question about viewing MD documents (excuse the little deviation from the main thread topic regarding fpdoc):

Is there an MD renderer created with free pascal that can be plugged into Apache webserver so that the MD files are rendered correctly in any browser?

I have created a lot of such documents for my projects but the only way I have found to display them correctly is via a plug-in to FireFox (does not work on Chrome) using a "file://nameofdoc" URL. :(

What I would like to do is put them into my private webserver (on Ubuntu 18) in the documentation section so I can access them anywhere and not just when I have file access to the documents.

Note: On our company's subversion server (Windows Server 16 with Visual Svn) these documents render perfectly when viewed in the repository browser, but I don't want to use that server since it is an in-office-only server. And I would anyway need to check the appearance *before* committing the files to svn.

Any suggestions?

Bo Berglund Developer in Sweden

Reply by email

Michael Van Canneyt
to Bo Berglund
Bo Berglund wrote 19 lines
On Sat, 2 Jan 2021 15:31:11 +0100 (CET), Michael Van Canneyt via fpc-pascal wrote: > > Hello ! > > I didn't make it quite in time for the new year, but still: > > The fpdoc engine (what is used to document the FPC & Lazarus units) > is now capable of outputting the documentation in markdown. > Question about viewing MD documents (excuse the little deviation from the main thread topic regarding fpdoc): Is there an MD renderer created with free pascal that can be plugged into Apache webserver so that the MD files are rendered correctly in any browser?

You can use for example this one to translate markdown to HTML:

https://github.com/luridarmawan/fpc-markdown

The demo shows how to use it. You can convert & view the markdown pages directly or coonvert to html and put the static files somewhere.

Michael.

Reply by email

Bo Berglund
to Michael Van Canneyt

On Mon, 4 Jan 2021 11:38:09 +0100 (CET), Michael Van Canneyt via fpc-pascal

Show quoted text 11 lines
> Is there an MD renderer created with free pascal that can be plugged > into Apache webserver so that the MD files are rendered correctly in > any browser? You can use for example this one to translate markdown to HTML: https://github.com/luridarmawan/fpc-markdown The demo shows how to use it. You can convert & view the markdown pages directly or coonvert to html and put the static files somewhere.

Thanks,
I will have a read and test it.
Need to figure out how to plug it into Apache too...

Bo Berglund Developer in Sweden

Reply by email