diff --git a/docs/content/SUMMARY.md b/docs/content/SUMMARY.md index 0c0ca3c2..13dcac86 100644 --- a/docs/content/SUMMARY.md +++ b/docs/content/SUMMARY.md @@ -3,5 +3,6 @@ * [Demo](demo.ipynb) * [Flexible Demo](flexible_demo.ipynb) * [Reference](reference/) +* [FAQ](faq/) * [Contributing](contributing.md) -* [Citation](citation.md) \ No newline at end of file +* [Citation](citation.md) diff --git a/docs/content/faq/SUMMARY.md b/docs/content/faq/SUMMARY.md new file mode 100644 index 00000000..5831c38b --- /dev/null +++ b/docs/content/faq/SUMMARY.md @@ -0,0 +1,7 @@ +* [What is the top-level interface?/What's the main entry point?](entry_point.md) +* [How do I get past the linting checks?](bypassing_lint.md) +* [How do all the abstract classes fit together?](abstract_structure.md) +* [How should I go about proposing a major change?](proposing_major_changes.md) +* [How should I approach collaborating on this?](begin_collaborating.md) +* [What do I do if I find a function without proper documentation?](missing_function_documentation.md) +* [What is the purpose of the design philosophy behind this code base?](design_structure.md) diff --git a/docs/content/faq/abstract_structure.md b/docs/content/faq/abstract_structure.md new file mode 100644 index 00000000..0807a8e9 --- /dev/null +++ b/docs/content/faq/abstract_structure.md @@ -0,0 +1 @@ +# How do all the abstract classes fit together? diff --git a/docs/content/faq/begin_collaborating.md b/docs/content/faq/begin_collaborating.md new file mode 100644 index 00000000..78c9678e --- /dev/null +++ b/docs/content/faq/begin_collaborating.md @@ -0,0 +1 @@ +# How should I approach collaborating on this? diff --git a/docs/content/faq/bypassing_lint.md b/docs/content/faq/bypassing_lint.md new file mode 100644 index 00000000..cef34796 --- /dev/null +++ b/docs/content/faq/bypassing_lint.md @@ -0,0 +1,27 @@ +# How do I get past the linting checks? + +The first thing you should do is install the visual studio code [Ruff +plugin](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff). This plugin is +going to solve the vast majority of issues you may come across while working on this project. Most +common issues the linter finds will be automatically fixed when saving files with this plugin. + +Some common issues caught by the lint checks cannot be automatically fixed. e.g. unknown types from +an outside package, print statements, commented out lines of code, etc... When encountering some of +these issues, there are a few options. + +If you are in the middle of working on something, and you simply want to commit your changes in +order to finish what you are doing later, you can edit the file `pyproject.toml` to allow you to +commit your files while temporarily ignoring lint. To do this you want to add an entry to the block +`tool.ruff.lint.per-file-ignores` with your file name as the key, and a list of any lint codes you want to +ignore within those files. Please note that you most likely will need to remove these rules before +submitting a pull request. In almost all cases there is a more permanent solution to skipping lint, +and adding rules to your working files should only be a temporary solution to allow the lint to get +out of your way while developing a work in progress. There are situations where lint needs to be +skipped in this way, but those are few and far between. Most of those situations have also already +been addressed. + +In cases where you may need a more permanent bypass of lint checks, you can create case exceptions +for individual lines see [docs for examples](https://docs.astral.sh/ruff/tutorial/#ignoring-errors). +Common cases where this is necessary is when a dependency has poor typing, and the linter complains +about references to those components in your code. More often than not, it is not necessary to skip +lines of files, and this should only be done as a last resort. diff --git a/docs/content/faq/design_structure.md b/docs/content/faq/design_structure.md new file mode 100644 index 00000000..4427aa00 --- /dev/null +++ b/docs/content/faq/design_structure.md @@ -0,0 +1 @@ +# What is the purpose of the design philosophy behind this code base? diff --git a/docs/content/faq/entry_point.md b/docs/content/faq/entry_point.md new file mode 100644 index 00000000..46f8f1cb --- /dev/null +++ b/docs/content/faq/entry_point.md @@ -0,0 +1 @@ +# What is the top-level interface?/What's the main entry point? diff --git a/docs/content/faq/index.md b/docs/content/faq/index.md new file mode 100644 index 00000000..3e8be923 --- /dev/null +++ b/docs/content/faq/index.md @@ -0,0 +1,7 @@ +# FAQ + +Use this for guide as a reference for any questions that may come up while coding in this project. A +lot of questions that have come up about tooling, and how to configure it have been answered here. +If anything comes up while working on the project, please do not hesitate to ask in the Open Source +Mechanistic Interpretabiliy slack, or in a GitHub issue. If it came up while you were working, then +it may come up for someone else, so adding it here can always be helpful. diff --git a/docs/content/faq/missing_function_documentation.md b/docs/content/faq/missing_function_documentation.md new file mode 100644 index 00000000..46071a18 --- /dev/null +++ b/docs/content/faq/missing_function_documentation.md @@ -0,0 +1 @@ +# What do I do if I find a function without proper documentation? diff --git a/docs/content/faq/proposing_major_changes.md b/docs/content/faq/proposing_major_changes.md new file mode 100644 index 00000000..2e42bd05 --- /dev/null +++ b/docs/content/faq/proposing_major_changes.md @@ -0,0 +1 @@ +# How should I go about proposing a major change?