Would like to contribute to the documentation

[kishankarun]

Hi,

@kkinder ,

I liked the puepy project

I was also a big fan of Vue.js.

I had been with python backend also since a while.

Listening to you in talkpython.fm , inspired me to try the puepy. Its really great! Kudos to your contribution to the opensource community!

I would like to contribute, probably with the documentation if it helps...

Could you please let me know your workflow?

Wishing you all the best for your project 👍

[kjbrawner22]

I would also like to help contribute!

[kkinder]

Wow, that's awesome. The documentation is in a separate Git repo. I just updated its README file with some contribution notes.

And sorry for the delayed reply -- had a lot going on the past few days. Cheers and thanks for contributing, this will be great. Let me know if you run into any stumbling blocks.

[kishankarun]

Thanks for providing the details... @kkinder

Thanks for letting me know the procedure to contribute to the documentation.

The introduction to mkdocs and mkdocs-material was helpful.

I was trying to use the puepy-mkdocs using plain python3 but got stuck.

Could you please help me?

I tried referring to the dockerfile to try using poetry and do the following

pip3 cache purge
poetry env use system
poetry config virtualenvs.create false
poetry lock --no-update
poetry install --no-interaction --no-ansi

Then I ran

$ mkdocs serve

But this gave the following error

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - includes\abbreviations.md
ERROR   -  mkdocstrings: puepy.Application could not be found
ERROR   -  Error reading page 'reference/application.md':
ERROR   -  Could not collect 'puepy.Application'

Aborted with a BuildError!

I think I had missed out something? Or is it the right way?

I find that includes\abbreviations.md is empty.

All these were done after doing the initial steps mentioned in the readme

Start by cloning the repo and using docker compose to serve the documentation:

git clone [email protected]:kkinder/puepy-mkdocs.git
cd puepy-mkdocs/


Initializing submodules
Because the documentation includes a peupy submodule, you need to initialize it too:

git submodule update --init --recursive

[kkinder]

Hmmmm. I'm not sure what the issue would be. It's not finding puepy in the path. Can you see if, in the environment you're running mkdocs, you can import puepy?

Just run python3 and then try importing puepy directly to see if it's in the path. If it's not, that's the issue, but that's confusing because it should be in the same directory as the docs, given it is a submodule.

[kishankarun]

Yes I am able to import puepy in the puepy-mkdocs folder

kishan.k >>>  puepy-mkdocs >>> main ≡ >>  3.11.9 >>> python
Python 3.11.9 (tags/v3.11.9:de54cf5, Apr  2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import puepy
>>>

This is the directory structure

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        29-07-2024  08:40 AM                .github
d-----        29-07-2024  08:40 AM                .idea
d-----        29-07-2024  08:40 AM                docs
d-----        29-07-2024  08:40 AM                puepy
d-----        29-07-2024  09:35 AM                __pycache__
-a----        29-07-2024  08:40 AM           4956 .gitignore
-a----        29-07-2024  08:40 AM             77 .gitmodules
-a----        29-07-2024  08:40 AM            143 docker-compose.yml
-a----        29-07-2024  08:40 AM            473 Dockerfile
-a----        29-07-2024  08:40 AM           3192 mkdocs.yml
-a----        29-07-2024  08:40 AM          68115 poetry.lock
-a----        29-07-2024  08:40 AM           1569 puepy_hooks.py
-a----        29-07-2024  08:40 AM            461 pyproject.toml
-a----        29-07-2024  08:40 AM           2494 README.md

BTW, I have initiated two pull requests on the puepy-mkdocs. Please check the same, and merge it accordingly.

Thanks

[kkinder]

Did you get it working?

Very odd that you can manage to import puepy in the same environment you're running mkdocs in. I'm at a bit of a loss... Is there any chance you can give me an exact script to run to try and replicate the issue?

[kkinder]

I replied over on your ticket on the mkdocs repo. I think only a couple of minor corrections are necessary.