search

haskell / alex

A lexical analyser generator for Haskell
https://hackage.haskell.org/package/alex
BSD 3-Clause "New" or "Revised" License
298 stars 82 forks source link

Convert documentation to rst #205

Closed andreasabel closed 2 years ago

andreasabel commented 2 years ago

This is a first stab at updating the old documentation (DocBook V4.2 XML file):

This also removes files from the cabal-sdist generated tarball, which have no function on hackage/stackage nor for cabal or stack:

Rendering at: https://haskell-alex.readthedocs.io/en/latest/

Unfortunately, https://alex.readthedocs.io/ is already taken.

Once this is approved, TODO:

UPDATE (2022-02-27):

ghost commented 2 years ago

https://github.com/haskell/alex/pull/205/commits/bc8b2ee4585da8cabe258d4f7b43ae5bc6c609e2 likewise deletes the TODO file from alex.cabal

Ericson2314 commented 2 years ago

Thanks @andreasabel! Can we add a .. code-block:: haskell somewhere to make syntax highlighting Haskell by default?

andreasabel commented 2 years ago

Thanks @andreasabel! Can we add a .. code-block:: haskell somewhere to make syntax highlighting Haskell by default?

I tried this, to get the Haskell parts highlighted, but the alex code gives a parse error in the highlighter, so nothing gets highlighted. There does not seem to be a pygments lexer for alex (nor flex): https://pygments.org/docs/lexers/

andreasabel commented 2 years ago

@simonmar @Ericson2314 : If you give me your readthedocs.org IDs, I can add you to the maintainers list for haskell-alex.

Ericson2314 commented 2 years ago

I just made an Ericson2314 one.

Ericson2314 commented 2 years ago

but the alex code gives a parse error in the highlighter

Is it possible to disable in that specific code block?

Ericson2314 commented 2 years ago

Also, do you know how to make it use the theme GHC https://downloads.haskell.org/ghc/latest/docs/html/users_guide/ and Cabal https://cabal.readthedocs.io/en/3.6/ use? Seems good to be consistent, and I must admit I like it better.

Ericson2314 commented 2 years ago

https://gitlab.haskell.org/ghc/ghc/-/commit/aeea92ef6ffa514793b1d37b38aaed3616c5c24a did the theme change for GHC, but I propose we do not vendor the theme.

Once this is merged, I can provide some Nix to package up the docs build.

@andreasabel since you lead the charge here, I would be happy to convert happy after, merely imitating what was done for Alex, to same you the drudgery.

ghost commented 2 years ago

apologies for the query

where GHC and Hackage packages are using readthedocs.org how consistent should the .css files be

ghost commented 2 years ago

rendered pages' source should be examined via the 'Page source' footer links

search-and-replace on the alex.xml file had allocated for the use of pandoc

single quotes lsquo ‘ and rsquo ’ are problematic

as is nbsp   from introduction.rst.txt

The resulting module is Haskell 98 compatible.

expect the similar when using search-and-replace on happy.xml

dollar $, ldquo “, mdash —, percnt %, rdquo ”

andreasabel commented 2 years ago

Also, do you know how to make it use the theme GHC downloads.haskell.org/ghc/latest/docs/html/users_guide and Cabal cabal.readthedocs.io/en/3.6 use? Seems good to be consistent, and I must admit I like it better.

This is sphinx_rtd_theme, I switch over to it. (I just had the default that sphinx-init gave me.)

I'll go and check the syntax highlighting options we have.

andreasabel commented 2 years ago

Ok, I switched to sphinx_rtd_theme with highlighting style sphinx.

I'd like to get rid of the old release notes, they are only of historic interest these days. @Ericson2314 : Maybe the CHANGELOG is the best place for them? Or shall we simply remove them (they are still in the docbook/alex.xml then)?

Ericson2314 commented 2 years ago

@andreasabel Yeah the change log is a good place for them. Maybe just convert it to reST too (I prefer that to markdown anyways) and then merging them is straightforward?

Ericson2314 commented 2 years ago

Two last things and then I think this is ready!

andreasabel commented 2 years ago

@andreasabel Yeah the change log is a good place for them. Maybe just convert it to reST too (I prefer that to markdown anyways) and then merging them is straightforward?

@Ericson2314 : It seems like .rst changelogs are not recognized by hackage (yet). Example:

So maybe markdown is a safer bet.

andreasabel commented 2 years ago 
* Could we put the new doc-specific stuff in `doc/.gitignore` rather than the root one? I think that is a nicer separation of concerns.

Sure!

(I thought I left this comment already but I guess I didn't or GitHub ate it)

Yes you did, but on the happy repo (and I implemented it there).

* Let's just delete the old docbook version? It's still in the repo history.

Fine with me.

andreasabel commented 2 years ago

@Ericson2314 : Done. Rendering updated: https://haskell-alex.readthedocs.io/en/latest/index.html

Ericson2314 commented 2 years ago

Awesome!

Ericson2314 commented 2 years ago

Can you add me to readthedocs so I can clone the settings for happy?

ghost commented 2 years ago

cf: https://cabal.readthedocs.io/en/3.6/getting-started.html#initializing-the-application

the background colour of shell commands is not the same as in the foregoing

for comparison

the Happy User Guide does not have an About sectionHappy User Guide

where Reporting Bugs, License and Obtaining Happy are subsections of the Introduction section

furthermore the Alex User Guide and Happy User Guide have numbered sections

andreasabel commented 2 years ago

@Ericson2314 : I added you as maintainer on https://readthedocs.org/projects/haskell-alex/. What remains to do is to set up the webhook so that the documentation will be automatically build when someone pushes to master or created a version tag. (But this needs admin rights on the github repo.)

@askeblad : Some polishing on the style might be necessary. So far, I have not invested so much time---I prefer an off-the-shelf solution here that has low maintenance burden. Cabal's sphinx setup is quite sophisticated, and they have their own style sheets. Also, some overhaul of the docs might be necessary. I haven't spend much time on this either, trying to get a transcription of the old docs out of the door...

ghost commented 2 years ago

it's understood that the conversion itself was the basis of this PR

whether the pandoc notes and comparison with happy code prove to be of use remains to be seen

Ericson2314 commented 2 years ago

Yeah @askeblad I would just great an issue for follup stuff. I agree matching the exact style is not important; the default read the docs theme is good enough for me, but content suggestions, and generally aligning the Happy Alex docs were appropriate, are worthwhile endeavours.