search

alan-turing-institute / empiarreader

Reader for EMPIAR datasets
BSD 3-Clause "New" or "Revised" License
9 stars 4 forks source link

Added sphinx documentation #58

Closed mooniean closed 11 months ago

mooniean commented 11 months ago

Added documentation for: Installation (from README) Contributing Guide Index

Resolves #45

@JatGreer feel free to add/remove what you think should be added, removed!

mooniean commented 11 months ago

the docs look all wonky, I'll try to fix them up a little bit.

JatGreer commented 11 months ago

Figured out i needed to do pip install .[doc] For some reason I get this error when I try to build docs locally:

$ sphinx-build -M html docs _docsbuild
Running Sphinx v4.3.2

Theme error:
no theme named 'pydata-sphinx-theme' found (missing theme.conf?)

despite having installed the package and checking the package uses dashes in pyproject.toml and uses underscores in conf.py (which is correct according to docs: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/install.html)

I might have a local version of sphinx which is too modern installed. So testing by pushing to github workflow instead.

Some links needed to be converted to rst format instead of md, but I don't remember making any other updates. There's still more we gotta add the the docs pages.

mooniean commented 11 months ago

@JatGreer why do you think the installation page doesn't get updated?

JatGreer commented 11 months ago

@mooniean I think it is because cd has special meaning in rst: https://docutils.sourceforge.io/docs/ref/rst/directives.html#compound-paragraph. Github highlighted it within the rst file - otherwise I wouldn't have found it. Escape char looks to be \. Hopefully this new commit should fix things for installation.rst