Mkdocs and GitHub Pages for documentation

[lewiuberg]

Hi!

Before doing anything, I will ask. What do you think of converting the docs to mkdocs and hosting it on ghpages?

Something like this: https://uberg.me/setup/usage/chocolatey/

[lewiuberg]

@caleb531 @eliotwrobson If you guys are interested, it looks like I will have time to do the whole mkdocs/materials setup and rewrite tonight. So please let me know if this is interesting 👍

[caleb531]

@lewiuberg That could definitely be a nicer experience for browsing documentation. @eliotwrobson What do you think?

[eliotwrobson]

I'm on board, I say go for it!! @lewiuberg we're still waiting on another big PR before v8, it should be no trouble to get this in as part of that release.

[lewiuberg]

Hi again @caleb531 and @eliotwrobson!

I've made a starting point for the new documentation, and will continue to work on it. It's a bit late here now, so I will probably continue tomorrow.

If you want to have a look at it so far just

Clone the repo:

git clone https://github.com/lewiuberg/automata/tree/mkdocs

Install the dependencies:

pip install -r requirements.dev.txt

Run the server:

mkdocs serve

And then go the local site:

http://127.0.0.1:8000/

[caleb531]

@lewiuberg The clone command should actually be:

git clone https://github.com/lewiuberg/automata.git
cd automata
git checkout mkdocs

But thank you for this! Will take a full look at this within the next few days (busy weekend for me 😅)

[caleb531]

@lewiuberg So... I got sidetracked, but I am finally testing this out now. A few observations:

One requirements file to rule them all

Since we have explicit library dependencies managed via pyproject.toml, it should be fine to have the docs dependencies as part of a single requirements.txt file (and I would personally prefer having a single file from which to install everything for development).

API Docs link in README navigates user to GitHub

At the end of the main README, I have a link to the index page for the API documentation. However, when I click this, I am taken out of the mkdocs website and redirected to the Automata API docs on GitHub.

Since mkdocs are meant to replace the API docs on GitHub, I suppose the obvious solution is to simply update the README to point that link to mkdocs instead of GitHub. And if we're going to do that, we should include the Migration Guide in mkdocs as well (since that is linked to from the README and relates to the API).

Warnings when running

When I set everything up and run mkdocs serve, the website is built and viewable just fine, but I receive the following warnings from the server (snippet below). Indeed, if I click the "Table of Contents" link on one of the subpages (e.g. the TM class), then I receive a 404.

I suppose the solution to the aforementioned issue would be to remove these links, since the sidebar navigation would be available instead.

WARNING  -  Both index.md and README.md found. Skipping README.md from
            /Users/caleb/Repositories/personal/automata-lewiuberg/docs
INFO     -  The following pages exist in the docs directory, but are not included
            in the "nav" configuration:
              - index.md
              - about.md
              - people.md
WARNING  -  Documentation file 'base-exception-classes.md' contains a link to
            'README.md' which is not found in the documentation files.
WARNING  -  Documentation file 'base-exception-classes.md' contains a link to
            'README.md' which is not found in the documentation files.
WARNING  -  Documentation file 'class-automaton.md' contains a link to
            'README.md' which is not found in the documentation files.
WARNING  -  Documentation file 'class-automaton.md' contains a link to
            'README.md' which is not found in the documentation files.
WARNING  -  Documentation file 'regular-expressions.md' contains a link to
            'README.md' which is not found in the documentation files.
WARNING  -  Documentation file 'regular-expressions.md' contains a link to
            'README.md' which is not found in the documentation files.
WARNING  -  Documentation file 'fa/class-dfa.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'fa/class-dfa.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'fa/class-fa.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'fa/class-fa.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'fa/class-gnfa.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'fa/class-gnfa.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'fa/class-nfa.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'fa/class-nfa.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'fa/examples.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'fa/examples.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'pda/class-dpda.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'pda/class-dpda.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'pda/class-npda.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'pda/class-npda.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'pda/class-pda.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'pda/class-pda.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'tm/class-dtm.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'tm/class-dtm.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'tm/class-mntm.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'tm/class-mntm.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'tm/class-ntm.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'tm/class-ntm.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'tm/class-tm.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'tm/class-tm.md' contains a link to 'README.md'
            which is not found in the documentation files.
WARNING  -  Documentation file 'tm/tm-exception-classes.md' contains a link to
            'README.md' which is not found in the documentation files.
WARNING  -  Documentation file 'tm/tm-exception-classes.md' contains a link to
            'README.md' which is not found in the documentation files.

cc @eliotwrobson (let me know if you have any thoughts on these things!)

[lewiuberg]

Yeah! As I said, "starting point", there are still loads of my personal links as well that have to go. I used my personal template project. I just wanted to know if you liked the overall theme etc, before I move forward cleaning up and polish the content.

[caleb531]

@lewiuberg Gotcha! I think the theme is generally fine. Only comment I might have is that I think the navigation feels a bit tucked away in the sidebar. I wish it were more in-sight and in-mind. But maybe that's just the way all the mkdocs themes are. Please let me know if I'm wrong!

[lewiuberg]

@caleb531 I think I could restructure it a bit and put more of it in the nav bar maybe. There is a lot of reformatting to do, to benefit from the different features of Materials as well. I hope to have a free night to work on this soon :)

[eliotwrobson]

Just as a heads up, as we are looking to submit this package to PyOpenSci, one of the requirements for submission there is having the docs on a separate site, as we are trying to do in this issue (see comment in the presubmission inquiry here: https://github.com/pyOpenSci/software-submission/issues/135#issuecomment-1724164864). In particular, the PyOpenSci documentation guidelines are listed here: https://www.pyopensci.org/python-package-guide/documentation/index.html.

Just something to keep in mind as work continues on this issue. There are a few other things that need to be closed out before the PyOpenSci submission, so no rush. Thanks again @lewiuberg for your initial work here! cc @caleb531

[lewiuberg]

I'll try to find some time to contribute more on this 👍🏻

[eliotwrobson]

@lewiuberg Since we closed out the JOSS review, I was wondering if you had any objections to me creating a feature branch based off of your initial work here? That way, we can all submit smaller PRs to the feature branch and work on it incrementally. @caleb531 any thoughts?

[caleb531]

@eliotwrobson That sounds good to me. Also, I was thinking that we could perhaps have the documentation site hosted on GitHub Pages in this repository or something.

[eliotwrobson]

Also, I was thinking that we could perhaps have the documentation site hosted on GitHub Pages in this repository or something.

That sounds reasonable. I think that's what the changes on @\lewiuberg's branch do, so it should be straightforward to set that up.

[eliotwrobson]

@caleb531 new branch is here https://github.com/caleb531/automata/tree/docs_rework

Not quite sure how to set this up as a github page that's a separate site, but I can try to start editing the text at some point.

[lewiuberg]

Are you going to get a domain and "hook" that up to the GitHub page?

[caleb531]

Are you going to get a domain and "hook" that up to the GitHub page?

@lewiuberg Possibly, although I don't think the documentation site necessarily needs a domain (since it hasn't had one so far).

[eliotwrobson]

Another note, since we also have to write docstrings for everything, I think we should use a docstrings API plugin for mkdocs: https://mkdocstrings.github.io/

[lewiuberg]

I dont mind that you open a feature branch. Sorry for not contributing more. In the hospital with my eldest son. I'll contribute more when he is better.

[lewiuberg]

I tested out mkdocstrings now. Works very well! like Sphinx .

PS! Here I use NumPy doctoring style.

[eliotwrobson]

@lewiuberg no worries and hope all is well with you! And thanks again for your contributions so far 🙂

And awesome that it works! It would be great if you opened a PR adding it to the feature branch (even if nothing has been changed yet with docstrings, I'm not even sure how to set up plugins so it would be a help 😅).

[lewiuberg]

Hi!

Have a look at this PR https://github.com/caleb531/automata/pull/180

I have to go to the hospital now, but I will check later. Please tell me which branch if this was the wrong branch @eliotwrobson. At bit hectic here now :)

[eliotwrobson]

Hey guys, just an update on this. Made a few pushes to the docs branch here: https://github.com/caleb531/automata/tree/docs_rework

I think I've gotten things looking reasonably well with the automated generation from docstrings. So I think the next step is just to port over all of the text from the markdown API documentation into the docstrings, then the automated generation will handle the rest. Feel free to make any incremental pushes to the branch.

cc @caleb531

[eliotwrobson]

Added docstrings for all the methods in the DFA class. Once the rest of the docstrings are done, it would be great to have the new site up in the next week or so, since I would like to start the PyOpenSci submission pretty soon.

[caleb531]

@eliotwrobson Sounds good. Let me know when you've finished working through the docstrings and I'll be happy to review any PRs you send my way!

[eliotwrobson]

@caleb531 makes sense! I might follow up with some PRs that move files around in anticipation of the submission. I might follow up over email if things get complicated.

[eliotwrobson]

Closing since the new docs site is deployed!