Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API documentation missing links #66

Closed
6 tasks done
ptheywood opened this issue Oct 20, 2021 · 6 comments · Fixed by #74
Closed
6 tasks done

API documentation missing links #66

ptheywood opened this issue Oct 20, 2021 · 6 comments · Fixed by #74
Assignees
Labels
bug Something isn't working

Comments

@ptheywood
Copy link
Member

ptheywood commented Oct 20, 2021

In a number of places (atleast 6) there are links intending to link to API docs, which do not do so.

The ones i've found are of the pattern:

Full API documentation for the ``X``: link

Where X is the name of a class, such aas EnvironmentDescription.

We could hardcode links to the hosted API docs, but this feels brittle. There should be a breathe/exhale way of finding the correct link, although I'm not sure exactly how.

Additionally, as the api docs are an optional part of the docs project, these links will only exist if the API docs are being built, which is (suprisingly) expensive in terms or time.

  • src/guide/6-agent-birth-death/1-agent-birth-device.rst:149
  • src/guide/6-agent-birth-death/3-agent-death.rst:53
  • src/guide/2-model-definition/3-agent.rst:152
  • src/guide/2-model-definition/2-environment.rst:137
  • src/guide/2-model-definition/1-model.rst:31
  • src/guide/3-behaviour-definition/1-defining-agent-functions.rst:170
@ptheywood ptheywood added the bug Something isn't working label Oct 20, 2021
@Robadob
Copy link
Member

Robadob commented Feb 1, 2022

Noticed some other issues on this page: https://docs.flamegpu.com/guide/3-behaviour-definition/6-host-functions.html

Bullets not formatted correctly:
image

Something odd going on around uniform here:

image

@Robadob
Copy link
Member

Robadob commented Feb 1, 2022

I wasn't aware of this issue when I was fixing cross ref's the other day, only noticed this earlier today, will try and address all the issues tomorrow. Just noticed they're cross ref's to API docs, might be a tad harder....

@Robadob Robadob self-assigned this Feb 1, 2022
@Robadob
Copy link
Member

Robadob commented Feb 2, 2022

https://exhale.readthedocs.io/en/latest/usage.html#linking-to-a-generated-file

This appears to be the guidance, will test.

@Robadob
Copy link
Member

Robadob commented Feb 2, 2022

Ok so writing

* Full API documentation for the ``EnvironmentDescription``: :class:`flamegpu::EnvironmentDescription`

produces a link like this.
image

And the link goes to api/classflamegpu_1_1_environment_description.html#_CPPv4N8flamegpu22EnvironmentDescriptionE

image

@Robadob
Copy link
Member

Robadob commented Feb 2, 2022

And if you want custom text, you use something like this

* Full API documentation for the ``EnvironmentDescription``: :class:`custom text<flamegpu::EnvironmentDescription>`

Not clear how to get rid of the inline code style, but that's probably not an issue, this will just allow us to omit the namespace inline.

image

@Robadob
Copy link
Member

Robadob commented Feb 2, 2022

The more info block at the bottom of src/guide/6-agent-birth-death/3-agent-death.rst:53 isn't even relevant, it appears copy pasted from a page related to environment.

@Robadob Robadob mentioned this issue Feb 2, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants