docs(mkdocs): migrating documentation engine #221

Naman-Priyadarshi · 2024-02-27T22:55:26Z

Pull Request description

Migrates the documentation engine of SciCookie from Jupyterbook to mkdocs with material theme

Fixes #176

How to test these changes

mkdocs serve

Pull Request checklists

This PR is a:

bug-fix
new feature
maintenance

About this PR:

it includes tests.
the tests are executed on CI.
the tests generate log file(s) (path).
pre-commit hooks were executed locally.
this PR requires a project documentation update.

Author's checklist:

I have reviewed the changes and it contains no misspelling.
The code is well commented, especially in the parts that contain more complexity.
New and old tests passed locally.

Additional information

~~I have not yet added the dependencies to SciCookie's installation files.~~
~~Also, have not removed the config files for jbook~~

The dependencies are:
markdown-callouts>=0.2
mkdocs>=1.3.1
mkdocs-include-exclude-files>=0.0.1
mkdocs-jupyter>=0.21
mkdocs-material>=8.3.9
mkdocstrings-python>=0.7.1
mkdocstrings-python-legacy>=0.2.3
pymdown-extensions>=9.5

Reviewer's checklist

Copy and paste this template for your review's note:

## Reviewer's Checklist

- [ ] I managed to reproduce the problem locally from the `main` branch
- [ ] I managed to test the new changes locally
- [ ] I confirm that the issues mentioned were fixed/resolved

Naman-Priyadarshi · 2024-02-28T16:03:34Z

Added dependencies to pyproject.toml under docs group

Naman-Priyadarshi · 2024-02-29T14:58:37Z

Could you please review it, @Saransh-cpp? Also, the tests seem to be failing because distlib is not installed. Should I add it to pyproject.toml?

Saransh-cpp

Thanks for working on this, @Naman-Priyadarshi!

pyproject.toml

Naman-Priyadarshi · 2024-03-11T12:04:13Z

Hey @Saransh-cpp , just a friendly reminder for the PR review! 😄

Saransh-cpp

Thanks for working on this, @Naman-Priyadarshi! The website looks really good now. Could you please also add site/ to .gitignore?

mkdocs.yml

Naman-Priyadarshi · 2024-03-12T09:38:21Z

I have made the requested changes, but it appears there are conflicts. Could you help me resolve these? I haven't solved conflicts using an IDE like VSCode before. I'm accustomed to using a web editor for conflict resolution, but that doesn't seem to be an option here

Saransh-cpp · 2024-03-12T10:43:56Z

Something like this should work:

git remote add upstream https://github.com/osl-incubator/scicookie    # link to the original scicookie repo
git pull upstream main --no-rebase   # pull the main branch without rebasing (rebasing is a bit intimidating for people)

Once done, you'll see that the command errors out. Go to the "Source Control" tab in VS Code (left pane) and you'll see files under "Merge changes" (IIRC) there. These are the files that have conflicts. Open the file from there itself and VS Code will show you the conflicted lines of code. You can then select which lines you want to keep using the VS Code GUI.

Once the conflicts are resolved -

git add .
git commit -m "Resolve conflicts"

Let me know if you need assistance over a google meet!

Naman-Priyadarshi · 2024-03-12T11:51:11Z

I'll try this and let you know! 😄

Naman-Priyadarshi · 2024-03-12T15:15:12Z

Something like this should work:

git remote add upstream https://github.com/osl-incubator/scicookie    # link to the original scicookie repo
git pull upstream main --no-rebase   # pull the main branch without rebasing (rebasing is a bit intimidating for people)

So, I used these commands and now git is listing that I have a lot of files to be committed

(cookie) namanpriyadarshi@Namans-MacBook-Air scicookie % git status
On branch migrate-doc-engine
Your branch is up to date with 'origin/migrate-doc-engine'.

You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Changes to be committed:
        modified:   .editorconfig
        new file:   .git-blame-ignore-revs
        modified:   .github/ISSUE_TEMPLATE.md
        modified:   .github/ISSUE_TEMPLATE/bug-report.yml
        modified:   .github/ISSUE_TEMPLATE/config.yml
        modified:   .github/ISSUE_TEMPLATE/documentation-report.yml
        modified:   .github/ISSUE_TEMPLATE/feature-request.yml
        modified:   .github/PULL_REQUEST_TEMPLATE.md
        modified:   .github/workflows/main.yaml
        modified:   .github/workflows/release.yaml
        modified:   .gitignore
        modified:   .pre-commit-config.yaml
        modified:   .prettierignore
        modified:   .releaserc.json
        modified:   CODE_OF_CONDUCT.md
        modified:   README.md
        modified:   docs/contributing.md
        modified:   docs/guide.md
        modified:   docs/index.md
        modified:   src/scicookie/cookiecutter.json
        modified:   src/scicookie/hooks/post_gen_project.py
        modified:   src/scicookie/profiles/base.yaml
        modified:   src/scicookie/profiles/osl.yaml
        modified:   src/scicookie/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/bug-report.yml
        modified:   src/scicookie/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/config.yml
        modified:   src/scicookie/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/documentation-report.yml
        modified:   src/scicookie/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/feature-request.yml
        modified:   src/scicookie/{{cookiecutter.project_slug}}/.github/PULL_REQUEST_TEMPLATE.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/.github/workflows/main.yaml
        modified:   src/scicookie/{{cookiecutter.project_slug}}/.github/workflows/release.yaml
        modified:   src/scicookie/{{cookiecutter.project_slug}}/.gitignore
        modified:   src/scicookie/{{cookiecutter.project_slug}}/.pre-commit-config.yaml
        new file:   src/scicookie/{{cookiecutter.project_slug}}/.prettierignore
        new file:   src/scicookie/{{cookiecutter.project_slug}}/.prettierrc.yaml
        modified:   src/scicookie/{{cookiecutter.project_slug}}/.releaserc.json
        modified:   src/scicookie/{{cookiecutter.project_slug}}/README.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/coc/CITIZEN.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/coc/CODE_OF_CONDUCT.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/coc/CONTRIBUTOR_CONVENANT.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/coc/CONTRIBUTOR_COVENANT.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/coc/NUMFOCUS_adapted_coc.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/coc/PYTHON_ADAPTED_COC.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/docs-jupyter-book/_toc.yml
        modified:   src/scicookie/{{cookiecutter.project_slug}}/docs-mkdocs/mkdocs.yaml
        modified:   src/scicookie/{{cookiecutter.project_slug}}/docs/contributing.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/docs/index.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/docs/installation.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/governance/numpy_governance.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/governance/sciml_governance.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/roadmap/ignite_roadmap.md
        modified:   src/scicookie/{{cookiecutter.project_slug}}/virtualenvs/conda/dev.yaml
        modified:   tests/smoke/linters.sh

Unmerged paths:
  (use "git add/rm <file>..." as appropriate to mark resolution)
        deleted by us:   docs/_config.yml
        deleted by us:   docs/_toc.yml

Saransh-cpp · 2024-03-12T15:21:27Z

That's correct!

If you go to the source control tab, it should show you the files which have conflicts -

Clicking on dev.yaml here should take you to GUI conflict resolver. The other two files can simply be deleted from the repository. After this add and commit!

…o migrate-doc-engine

Naman-Priyadarshi · 2024-03-12T16:18:12Z

Thank You @Saransh-cpp , this did the trick!

Saransh-cpp

Thanks, @Naman-Priyadarshi! This looks amazing now!

github-actions · 2024-03-12T19:00:20Z

🎉 This PR is included in version 0.7.0 🎉

The release is available on:

0.7.0
GitHub release

Your semantic-release bot 📦🚀

Naman-Priyadarshi force-pushed the migrate-doc-engine branch from f4bb8f5 to 99996fa Compare February 29, 2024 14:23

Naman-Priyadarshi marked this pull request as ready for review February 29, 2024 14:49

Saransh-cpp requested changes Feb 29, 2024

View reviewed changes

pyproject.toml Show resolved Hide resolved

Naman-Priyadarshi force-pushed the migrate-doc-engine branch from 79a6ea0 to 7c6733c Compare February 29, 2024 17:56

Naman-Priyadarshi added 7 commits March 2, 2024 02:48

added mkdoc.yml

2d5e5e7

add dependencies

d3ada0a

update poetry.lock as per pyproject.toml

6aa05f0

updating makim to use mkdocs

f24f337

remove jupyter-book config

3e7fd3f

add paginate to pyproject.toml

66844dd

add distlib as dependency

846f452

Naman-Priyadarshi force-pushed the migrate-doc-engine branch from 7c6733c to 846f452 Compare March 1, 2024 21:18

Naman-Priyadarshi and others added 2 commits March 5, 2024 21:55

Merge branch 'main' into migrate-doc-engine

4eb4278

add paginate to conda

9d1e259

Naman-Priyadarshi requested a review from Saransh-cpp March 5, 2024 16:56

Saransh-cpp requested changes Mar 11, 2024

View reviewed changes

mkdocs.yml Outdated Show resolved Hide resolved

mkdocs.yml Outdated Show resolved Hide resolved

Naman-Priyadarshi added 3 commits March 12, 2024 14:44

add site/ to .gitignore

da78789

remove extra css from docs build

9a8aeeb

remove sphinx doc from .gitignore

90574e0

Merge branch 'main' of https://github.com/osl-incubator/scicookie int…

ac32a2c

…o migrate-doc-engine

Naman-Priyadarshi requested a review from Saransh-cpp March 12, 2024 16:20

Saransh-cpp approved these changes Mar 12, 2024

View reviewed changes

Saransh-cpp merged commit 9da595f into osl-incubator:main Mar 12, 2024
11 checks passed

Naman-Priyadarshi deleted the migrate-doc-engine branch March 12, 2024 17:32

github-actions bot added the released label Mar 12, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(mkdocs): migrating documentation engine #221

docs(mkdocs): migrating documentation engine #221

Naman-Priyadarshi commented Feb 27, 2024 •

edited

Loading

Naman-Priyadarshi commented Feb 28, 2024

Naman-Priyadarshi commented Feb 29, 2024

Saransh-cpp left a comment

Naman-Priyadarshi commented Mar 11, 2024

Saransh-cpp left a comment

Naman-Priyadarshi commented Mar 12, 2024

Saransh-cpp commented Mar 12, 2024

Naman-Priyadarshi commented Mar 12, 2024

Naman-Priyadarshi commented Mar 12, 2024

Saransh-cpp commented Mar 12, 2024

Naman-Priyadarshi commented Mar 12, 2024

Saransh-cpp left a comment

github-actions bot commented Mar 12, 2024

docs(mkdocs): migrating documentation engine #221

docs(mkdocs): migrating documentation engine #221

Conversation

Naman-Priyadarshi commented Feb 27, 2024 • edited Loading

Pull Request description

How to test these changes

Pull Request checklists

Additional information

Reviewer's checklist

Naman-Priyadarshi commented Feb 28, 2024

Naman-Priyadarshi commented Feb 29, 2024

Saransh-cpp left a comment

Choose a reason for hiding this comment

Naman-Priyadarshi commented Mar 11, 2024

Saransh-cpp left a comment

Choose a reason for hiding this comment

Naman-Priyadarshi commented Mar 12, 2024

Saransh-cpp commented Mar 12, 2024

Naman-Priyadarshi commented Mar 12, 2024

Naman-Priyadarshi commented Mar 12, 2024

Saransh-cpp commented Mar 12, 2024

Naman-Priyadarshi commented Mar 12, 2024

Saransh-cpp left a comment

Choose a reason for hiding this comment

github-actions bot commented Mar 12, 2024

Naman-Priyadarshi commented Feb 27, 2024 •

edited

Loading