apaam/mlpack
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Overhaul documentation homepage (#3836)

Browse Source 
* Add pipeline to documentation homepage.

* Fix for mobile devices.

* Add little pipelines to go at the top of each page.

* Overhaul index page.

* Overhaul README to remove redundant material.

* Add installation documentation.

* Update pipelines.

* Allow nesting of deeper details.

* Add a pipeline to the top of the load/save page.

* Add prerequisites link to main pipeline.

* Add better but not finished sidebar.

* Add a couple new documentation pages.

* Fix URLs in svg.

* Incremental checkin.

* Fix Youtube URLs.

* Incremental checkin.

* Minor fixes.

* Add first pass at evaluation/deployment pages.

* Minor spacing and link fixes.

* Flesh out a number of additional pages and write basic compilation documentation.

* Fix some minor issues, and add Docker deployment page (not totally finished yet).

* Add developer documentation landing page.

* Hopefully getting close to the final set of changes here.

* Remove this documentation for now.

* Fix a few links, and the size of the sidebar.

* Fix some additional links.

* Fix a bunch more links.

* Fix another link that now has a better place.

* Refactor test-docs.sh to handle documentation that is a standalone program.

* Fix file exclusions.

* Fully qualify typename.

* Update name of file.

* Fix syntax error.

* Remove files that are not meant to be compiled.

* Also skip the quickstart.

* Move quickstart entry to the top.

* Remove gray coloring of binding documentation.

* Update name of sidebar link.

* Update to working link.

* Fix Wikipedia anchor.
This commit is contained in:
Ryan Curtin
2024-12-20 13:36:12 -05:00
committed by GitHub
parent 69b296b8c5
commit c8eb3dceac
71 changed files with 2691 additions and 863 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/test-docs.sh
+76 -81
View File
@@ -77,70 +77,90 @@ extract_code_blocks()
# preceding fence close above it.
last_line_fence=1;
# Track whether or not the entire last file corresponded to a class
# declaration.
class_decl=0;
while IFS= read -r line;
do
if [[ $last_line_fence == 1 ]];
then
# Skip this line---it will be a fence opening.
last_line_fence=0;
# Create main() function to wrap the code in.
echo "#include <mlpack.hpp>" > $output_prefix$output_file_display.cpp;
echo "" >> $output_prefix$output_file_display.cpp;
# If we have a class declaration from the previous file, insert it.
if [[ $class_decl == 1 ]];
then
class_decl=0;
last_output_file_id=$(($output_file_id - 1));
last_output_file_display=$(printf "%02d" $last_output_file_id);
cat $output_prefix$last_output_file_display.cpp | awk '
BEGIN { p=0 }
/int main()/ { p=1 }
/^{/ { if(p == 1) { p=2; o=1 } }
/^}/ { p=0; }
// { if (p == 2 && o == 0) { print substr($0, 3) } o=0 }' >> $output_prefix$output_file_display.cpp;
echo "" >> $output_prefix$output_file_display.cpp;
rm -f $output_prefix$last_output_file_display.cpp;
fi
echo "int main()" >> $output_prefix$output_file_display.cpp;
echo "{" >> $output_prefix$output_file_display.cpp;
continue;
fi
if [[ $line == '```'* ]];
if [[ $line == '```' ]];
then
last_line_fence=1;
# Close main() function.
echo "}" >> $output_prefix$output_file_display.cpp;
# Check after the fact: was this file only a class declaration? If so, we
# want to put it instead into the next file.
has_class1=`grep '^ class\|^ struct' $output_prefix$output_file_display.cpp | wc -l`;
has_class2=`grep '^ };' $output_prefix$output_file_display.cpp | wc -l`;
if [[ "$has_class1" != "0" && "$has_class2" != "0" ]];
if [ -f $output_prefix$output_file_display.body.cpp ];
then
class_decl=1;
fi;
# Determine whether we need a main() function for the code. Also check
# whether the file is simply a class definition, in which case we don't
# need to do anything except prepare it to be inserted into the next
# example.
has_main=`grep 'int main(' $output_prefix$output_file_display.body.cpp | wc -l`;
has_class1=`grep '^ class\|^ struct' $output_prefix$output_file_display.body.cpp | wc -l`;
has_class2=`grep '^ };' $output_prefix$output_file_display.body.cpp | wc -l`;
class_decl=0;
if [ $has_class1 -ne 0 -a $has_class2 -ne 0 ];
then
class_decl=1;
fi;
# Detect if we need any to add any special headers. We have to do this
# when we finish with the file...
if [[ `grep 'Eigen::' $output_prefix$output_file_display.cpp | wc -l` -gt 0 ]];
then
sed -i '1s/^/#include <Eigen\/Dense>\n/' $output_prefix$output_file_display.cpp;
fi
if [ $has_main -eq 0 -a $class_decl -eq 0 ];
then
# Create main() function to wrap the code in.
echo "#include <mlpack.hpp>" > $output_prefix$output_file_display.cpp;
echo "" >> $output_prefix$output_file_display.cpp;
if [[ `grep 'xt::' $output_prefix$output_file_display.cpp | wc -l` -gt 0 ]];
then
sed -i '1s/^/#include <xtensor\/xrandom.hpp>\n/' $output_prefix$output_file_display.cpp;
sed -i '1s/^/#include <xtensor\/xarray.hpp>\n/' $output_prefix$output_file_display.cpp;
# Insert any class definitions.
if [ -f $output_prefix$output_file_display.defn.cpp ];
then
cat $output_prefix$output_file_display.defn.cpp >> $output_prefix$output_file_display.cpp;
rm -f $output_prefix$output_file_display.defn.cpp;
fi
echo "int main()" >> $output_prefix$output_file_display.cpp;
echo "{" >> $output_prefix$output_file_display.cpp;
# Insert the code itself.
cat $output_prefix$output_file_display.body.cpp >> $output_prefix$output_file_display.cpp;
rm -f $output_prefix$output_file_display.body.cpp;
# Close main() function.
echo "}" >> $output_prefix$output_file_display.cpp;
elif [[ "$class_decl" == "1" ]];
then
# If the function is only a class declaration, set it aside, along
# with any other declarations, for the next program.
next_id=$(($output_file_id + 1));
next_display=$(printf "%02d" $next_id);
if [ -f $output_prefix$output_file_display.defn.cpp ];
then
mv $output_prefix$output_file_display.defn.cpp $output_prefix$next_display.defn.cpp;
cat $output_prefix$output_file_display.body.cpp >> $output_prefix$next_display.defn.cpp;
rm -f $output_prefix$output_file_display.body.cpp;
else
mv $output_prefix$output_file_display.body.cpp $output_prefix$next_display.defn.cpp;
fi
else
# The file should be able to compile on its own.
mv $output_prefix$output_file_display.body.cpp $output_prefix$output_file_display.cpp;
fi
# Detect if we need any to add any special headers. We have to do this
# when we finish with the file...
if [ -f $output_prefix$output_file_display.cpp ];
then
if [[ `grep 'Eigen::' $output_prefix$output_file_display.cpp | wc -l` -gt 0 ]];
then
sed -i '1s/^/#include <Eigen\/Dense>\n/' $output_prefix$output_file_display.cpp;
fi
if [[ `grep 'xt::' $output_prefix$output_file_display.cpp | wc -l` -gt 0 ]];
then
sed -i '1s/^/#include <xtensor\/xrandom.hpp>\n/' $output_prefix$output_file_display.cpp;
sed -i '1s/^/#include <xtensor\/xarray.hpp>\n/' $output_prefix$output_file_display.cpp;
fi
fi
fi
output_file_id=$(($output_file_id + 1));
@@ -150,35 +170,10 @@ extract_code_blocks()
fi
# Include indentation (two spaces).
echo " $line" >> $output_prefix$output_file_display.cpp;
echo " $line" >> $output_prefix$output_file_display.body.cpp;
done < $input_file.tmp;
# The last file is always invalid---we opened it without knowing whether
# anything would be in it.
rm -f $output_prefix$output_file_display.cpp;
# Check the "true" last file: if it's only class declarations, no need to
# compile it.
output_file_id=$(($output_file_id - 1));
output_file_display=$(printf "%02d" $output_file_id);
if [ -f $output_prefix$output_file_display.cpp ];
then
cat $output_prefix$output_file_display.cpp | awk '
BEGIN { p=0 }
/int main()/ { p=1 }
/^{/ { if(p == 1) { p=2; o=1 } }
/^}/ { p=0 }
// { if (p == 2 && o == 0) { print substr($0, 3) } o=0 }' >> $output_prefix$output_file_display.cpp.tmp;
has_class1=`grep '^class' $output_prefix$output_file_display.cpp.tmp | wc -l`;
has_class2=`grep '^};' $output_prefix$output_file_display.cpp.tmp | wc -l`;
if [[ "$has_class1" != "0" && "$has_class2" != "0" ]];
then
# The file's main() function is just a class declaration. Nuke it.
rm -f $output_prefix$output_file_display.cpp;
fi
rm -f $output_prefix$output_file_display.cpp.tmp;
fi
rm -f $output_prefix*.defn.cpp; # Remove any unused definitions.
rm -f $input_file.tmp;
}
@@ -338,16 +333,18 @@ do
declare -a files_to_skip=(
# These files have small incomplete snippets that can't compile into
# standalone programs.
"sample_ml_app.md"
"deploy_windows.md"
"hpt.md"
"cv.md"
"timer.md"
"bindings.md"
"elemtype.md"
"iodoc.md"
"distances.md"
"elemtype.md"
"kernels.md"
"metrics.md"
"trees.md"
# Skip the quickstart, since it depends on some specific data.
"cpp.md"
# The tutorials are old and are likely to be replaced, so let's not test
# them.
"amf.md"
@@ -369,8 +366,6 @@ do
"q_learning.md"
"sac.md"
"td3.md"
# Skip quickstarts, although we should eventually test them.
"cpp.md"
);
skip=0;