Your Project with Great Documentation.

Just as discussed in #47 with the Google Docstring format, it would be great to have support for NumPy Docstrings; An example of which can be found here.

On my generated docs the "View Source" Block is not working. The button is not visible and the source code is displayed without formatting etc.

As you can see here: https://fri.lpfann.me/reference/fri/parameter_searcher/

I used version 1.3.

First off, I want to thank you for this very interesting project!

I was trying to use portray for my project, and found that it broke when I tried to run

portray in_browser

It said

UserWarning: Unable to identify `repo_name` and `repo_url` automatically

I looked through the code and found that this was issued because portray could not determine the name of my project from the git remote. I seldom use http for cloning, preferring ssh myself and since I also use Azure Devops during working hours I have remotes looking like

[email protected]:v3/username/projectname/reponame

This origin-remote will be ignored by the if-clause in config.py#L141.

Could you have a look at below logs? Thank you.

Portray version

• v1.2.4

Target repository

• https://github.com/ki4070ma/python-client

Logs

➜  python-client git:(portray) ✗ portray as_html -m appium
/Users/atsushimori/.pyenv/versions/3.7.3/lib/python3.7/site-packages/portray/config.py:98: UserWarning: Error (malformed node or string: <_ast.Call object at 0x107b27588>) occurred trying to parse setup.py file: /Users/atsushimori/github/ki4070ma/python-client/setup.py
  warnings.warn(f"Error ({error}) occurred trying to parse setup.py file: {location}")
/Users/atsushimori/.pyenv/versions/3.7.3/lib/python3.7/site-packages/portray/config.py:129: UserWarning: No /Users/atsushimori/github/ki4070ma/python-client/pyproject.toml config file found
  warnings.warn(f"No {location} config file found")
/Users/atsushimori/.pyenv/versions/3.7.3/lib/python3.7/site-packages/portray/config.py:148: UserWarning: Unable to identify `repo_name` and `repo_url` automatically
  warnings.warn("Unable to identify `repo_name` and `repo_url` automatically")
Module not found: appium.webdriver.extensions.activities

Others

• appium.webdriver.extensions.activities doesn't exist in above repository.
• I could run portray for another project successfully in my local.
  • https://github.com/ki4070ma/change-passwd-func/tree/gh-pages

I get this traceback:

$ portray in_browser
 ....
  File ".../lib/python3.6/site-packages/portray/config.py", line 63, in project
    raise NoProjectFound(directory)
portray.exceptions.NoProjectFound: (NoProjectFound(...), "No Python project found in the given directory: 

Clarification in the error message and in the documentation for what defines a "Python project" would help.

E.g. do you require that Poetry be used and/or that there be a pyproject.toml file?

First of all thanks for this awesome project! I was really looking for something like this!

I found a couple of issues concerning the configuration of mkdocs. If i add the following configuration to the pyproject.toml file:

nav = ["docs/index.md", "docs/page2.md"]

i get kind of the desired result. There are two issues coming up if i do this:

1. The very first page is see (when rendering the pages by "portray in_browser") is the rendered page of my README.md file (although i did not list it in nav)! If i navigate to a different page, this first README page is not reachable any more as there is, as desired, no link to README in the navigation bar on the left.

2. The reference entry in the navigation bar, which usually contains the API documentation, is missing completely. Do i need to do some extra configs in order to get it again?

Concerning the 'nav' entry, there is an additional problem. Originally mkdocs uses a .yml file for its configuration. In yaml, it is valid to have a list (array) of mixed types e.g.:

nav: - Overview: index.md - page2.md

which is a list of a key-value type and a string type. mkdocs uses this as the keys in the array are used to name the pages generated. In this example, index.md would be named 'Overview' and page2 would be name either as page2 or like the caption defined in page two (if any given).

Right now, the only format which is accepted by portray is to give a list of strings (as done above). Thus it is not possible to name your pages differently. In TOML you would need to accept something like

nav = {Overview = "index.md", ABC = "page2.md"}

which is a list of key-value pairs.

The problem is, that TOML does not allow for mixed types in arrays (up to my knowledge, please correct me if i am wrong about this). Thus, you would need two lists in the pyproject.toml file, one as a plain list of strings and one as key-value pair, to achieve the same functionality as possbile with the .yml file. Or you force the user to go for one of the two possibilities.

Anyway, i really would like to use this functionality! Thanks in advance!

I ran portray in_browser and all works great except when I update for example the README.MD, it is not reflected in the browser. It is identified in the output of portray:

[I 220114 16:44:29 handlers:92] Reload 1 waiters: D:\Projects\aim\README.md
[I 220114 16:44:29 handlers:135] Browser Connected: http://127.0.0.1:8000/
[I 220114 16:44:42 handlers:92] Reload 1 waiters: D:\Projects\aim\README.md
[I 220114 16:44:42 handlers:135] Browser Connected: http://127.0.0.1:8000/

I have tried clearing my cache as well as different browsers with no luck. It does work if I kill and restart. Any help would be appreciated. Here is my config:

[tool.portray.mkdocs.theme]
name = "material"
palette = {primary = "blue grey", accent = "pink"}

Thank you.

This is a mkdocs compatibility fix pointed out by @Peter200lx .

To help avoid surprises like this, I was wondering if it would make sense to pin an exact version of mkdocs (and others). Currently, only a major version is specified:

https://github.com/timothycrosley/portray/blob/371ab8bce9ebd0ba6b77bc5e8c1d318a0e3aa428/pyproject.toml#L12

The following line needs to be updated to support mkdocs 1.2: https://github.com/timothycrosley/portray/blob/cd60f2a22d18ec025fb341c0010de31b2523a1a2/portray/render.py#L172

https://github.com/mkdocs/mkdocs/blob/master/docs/about/release-notes.md#backward-incompatible-changes-in-12

The mkdocs.config.DEFAULT_SCHEMA global variable has been replaced with the function mkdocs.config.defaults.get_schema(), which ensures that each instance of the configuration is unique (mkdocs/mkdocs#2289).

As suggested in #58 this ups the requirements for mkdocs-material to ^5.0 and pymdown-extensions to ^7.0.

Since it changes the package's requirements, it may warrant a minor version bump for portray itself, but I'll let @timothycrosley be the judge of that.

This was hard coded to pretend every error is "file not found."

So change to explicitly checking if file exists for that message, otherwise log the exception message.

Before, with present pyproject.toml file, but lopsided quotes / missing a closing quote:

/home/CENSORED/projects/AdvancedHTMLParser/myenv/lib/python3.6/site-packages/portray/config.py:137: UserWarning: No /home/CENSORED/projects/AdvancedHTMLParser/./pyproject.toml config file found
  warnings.warn(f"No {location} config file found")

After the change:

/home/CENSORED/projects/AdvancedHTMLParser/myenv/lib/python3.6/site-packages/portray/config.py:143: UserWarning:
Config file at "/home/CENSORED/projects/AdvancedHTMLParser/./pyproject.toml" has errors: Unbalanced quotes (line 2 column 118 char 132)
  warnings.warn(f'\nConfig file at "{location}" has errors: {loadConfigE}')

After the change, but with missing file:

/home/CENSORED/projects/AdvancedHTMLParser/myenv/lib/python3.6/site-packages/portray/config.py:121: UserWarning:
No config file found at location: "/home/CENSORED/projects/AdvancedHTMLParser/pyproject.toml"
  warnings.warn(f'\nNo config file found at location: "{location}"')

Not sure why you're using warnings... either get one super long line followed by a duplicate (but including source code!), or after my change get one less long line, one that contains the error message, and then source cod again.

I would use sys.stderr.write, myself, for just one line. Can make a decorator for "one time" error display, though I think this will always be once. Example here: https://github.com/kata198/indexedredis/blob/master/IndexedRedis/deprecated.py defines a decorator to print a message max once per run, can just call that directly if such is your intent.

I did not include such in this merge request, I kept with warnings.

Thanks!

(Newer version of #58)

The latest major version of pymdown-extensions includes support for, among other things:

• Language-specific syntax highlighting
• Rendering Mermaid diagrams (via an extension)

@timothycrosley , are you open to a PR updating the dependency requirements?

When I run portray to autogenerate docs, it is producing pages for files that are out of date and do not exist any more.

I have not been able to generate docs for the current state no matter what I do.

Commands I have tried, that all produce the same out of date documentation pages. portray in_browser portray in_browser -r portray server -o portray server -o -r portray as_html

Other things I have tried

• Controll-C portray, and rerun it again.
• Pip uninstall and reinstall portray

pip uninstall portray
pip install portray

• Remove any build, .venv, pyproject.toml files, and the output docs are still the same
• Duplicate folder, and remove everything unrelated to the project, even the .git folder. The docs still creates documentation for old code, including a file that does not even exist anymore.

All of these produce the exact same result with no distinguishable change.

Background

The current functionality takes the markdown files and converts them as they stand, and add links back to the source repository (if one exists). In some cases, the docs are shared with users for consumption only, without the desire to access to the underlying repository.

Scope

• [ ] Add configuration option to allow disabling references back to the repository
  • [ ] When disabled, the "edit" button on pages should be removed
  • [ ] When disabled, hyperlinks for badges should be removed

My docs/ directory contains an index.md which is used for the homepage instead of the project readme (I separate developer and user documentation this way). So I get this output when running portray in_browser:

Rendering complete website from Markdown using MkDocsBoth index.md and readme.md found. Skipping readme.md from /var/folders/2n/8zdpr6fn3djbww0vts_jl_n40000gp/T/tmpq3yfpg_c/input

This part works fine. However, for some reason the edit link on the homepage then does not include the string /docs, instead linking to <my_repo>/[edit_uri] without the trailing /docs. The link is incorrect and results in a 404.

MkDocs uses edit/master as the default edit_uri value, so without documentation stating otherwise I expected this to be the same in Portray, particularly because the documentation on edit_uri points to the documentation in MkDocs. Unifying this value with MkDocs would break clients, but it would be helpful to just let the user know that this is happening. A single-line message like, "edit_uri not set by user, defaulting to edit/main" (or edit/default) would be helpful.